ela
Contents

ManualPackages

Asking the user

In the terminalela --spec asking-the-user

Prompts at the terminal, in the ask package: a line, a secret, yes or no, and a choice from a list. A prompt reads the terminal itself (/dev/tty), never stdin, so it works the same under ela deploy.ela, ela < deploy.ela and cmd | ela, and a command's input or the script's own text is never taken as the answer. It replaces Bash's read and select.

Built-inDoes
ask.line(question)Returns the line the user types, without its newline
ask.secret(question)Returns the line typed with echo off; every message shows it as <secret>
ask.yes(question, default = false)Returns true or false: y, yes, n or no in any case; Enter alone gives default
ask.choose(question, options, many = false)Returns the item picked from the list; with many = true, a list of the items marked
name   = ask.line("Name?")token  = ask.secret("Token?")if ask.yes("Delete 3 files?")    rm $filesend iftarget = ask.choose("Deploy to?", ["staging", "production"])hosts  = ask.choose("Restart which?", $hosts, many = true)

What the terminal shows, the answers typed after the first three questions, and the list drawn under the fourth while it is open:

Name? AdaToken?Delete 3 files? [y/N] yDeploy to?▸ staging  production↑↓ move · type to narrow · enter picks · esc stops
  • The question. Each prompt prints the question and a space; ask.yes puts its hint between them. The answer is always the type its proc gives: ask.line and ask.secret a string, so converting it is explicit, int(ask.line("How many?")).
  • ask.secret. What is typed is not shown, and the terminal is put back as it was however the read ends, Ctrl-C and Ctrl-D included. The answer is a secret: every message, and vars, shows it as <secret>, and ela --lint warns of it in a command's arguments (Keyring, Secrets in commands).
  • ask.yes. The hint shows the default, [y/N] when it is false and [Y/n] when it is true, so a question before deleting is safe by default. Anything but y, yes, n, no or an empty line asks again.
  • ask.choose. The options are listed under the question with ▸ on the one picked; the arrow keys, Home, End, Page Up and Page Down move, and typing narrows the list to the options holding what is typed, case aside, Backspace widening it again. Enter picks. The item comes back as the list holds it, a number as a number; a list of anything but text and numbers is shown as ela writes it. With many = true each option has a [ ], Space marks or unmarks the one under ▸, and Enter ends with the items marked, in the list's order; none marked gives []. Ten options show at once, fewer in a short window, and a longer list scrolls. Once answered the list is rubbed out and the question stands with the answer after it, Deploy to? staging, the items marked joined by , . An empty list is an error.
  • Ctrl-C. Ctrl-C at any prompt, or Esc at ask.choose, stops the script as Ctrl-C does anywhere else: with no catch signal INT or defer, ela ends by the signal, status 130; with one, the prompt's line fails as a command stopped by Ctrl-C does, and the catch block or the deferred lines run (LANGUAGE.md, catch signal). At the interactive prompt the line stops and the prompt comes back.
  • Ctrl-D instead of an answer is an error: the input ended.
  • No terminal. Under cron, CI or a service, in a pipe with no terminal, or in a browser page, a prompt is an error at its line, naming the question and saying to pass the answer another way:
deploy.ela:4:12: error: ask.yes needs a terminal to ask "Delete 3 files?", and stdin is not one; pass the answer another way, e.g. a --yes flag the script reads
  • Prompts work inside with screen, which shows a block on the terminal's alternate screen and gives the screen back at end with (LANGUAGE.md, with screen).