ask:
  short: get user input
  description: >
    Gets a line of user input text with a prompt.
  note: >
    When a program is receiving input from a pipe or writing its
    output to a pipe, this flag (which is enabled by default) forces the program
    to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which
    circumvents the pipe. This means that `foo | ./tomo your-program | baz` will
    still show a visible prompt and read user input, despite the pipes. Setting
    this flag to `no` will mean that the prompt is written to `stdout` and input
    is read from `stdin`, even if those are pipes.
  return:
    type: 'Text?'
    description: >
      A line of user input text without a trailing newline, or empty text if
      something went wrong (e.g. the user hit `Ctrl-D`).
  args:
    prompt:
      type: 'Text'
      description: >
        The text to print as a prompt before getting the input.
    bold:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether or not to print make the prompt appear bold on a console.
    force_tty:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether or not to force the use of /dev/tty.
  example: |
    assert ask("What's your name? ") == "Arthur Dent"

breakpoint:
  short: stop in the debugger
  description: >
    Stops the program in a debugger at the point where it is called. Running
    the program under `tomo run --debug` gives a debugger prompt here, showing
    the surrounding source and the values of the variables in scope.
  note: >
    Only a program compiled with `--debug` contains this call at all. Without
    that flag it compiles to nothing, so a `breakpoint()` left in the source
    costs a release build nothing and does nothing if the program is run
    outside a debugger. See `docs/debugging.md`.
  args: {}
  return:
    type: 'Void'
    description: >
      Nothing.
  example: |
    total := 0
    for i in 10
        total += i
    breakpoint() # `tomo run --debug` stops here, with `total` and `i` in scope

exit:
  short: exit the program
  description: >
    Exits the program with a given status and optionally prints a message.
  return:
    type: 'Abort'
    description: >
      This function never returns.
  args:
    message:
      type: 'Text?'
      default: 'none'
      description: >
        If nonempty, this message will be printed (with a newline) before
        exiting.
    status:
      type: 'Int32'
      default: 'Int32(1)'
      description: >
        The status code that the program with exit with.
  example: |
    exit("Goodbye forever!", Int32(1))

at_cleanup:
  short: register a cleanup function
  description: >
    Register a function that runs at cleanup time for Tomo programs. Cleanup
    time happens when a program exits (see `atexit()` in C), or immediately
    before printing error messages in a call to `fail()`. This allows for
    terminal cleanup so error messages can be visible as the program shuts
    down.
  note: >
    Use this API very carefully, because errors that occur during cleanup
    functions may make it extremely hard to figure out what's going on. Cleanup
    functions should be designed to not error under any circumstances.
  args:
    fn:
      type: 'func()'
      description: >
        A function to run at cleanup time.
  return:
    type: 'Void'
    description: >
      Nothing.
  example: |
    at_cleanup(func()
        _ := (/tmp/file.txt).remove(ignore_missing=yes)
    )

getenv:
  short: get an environment variable
  description: >
    Gets an environment variable.
  return:
    type: 'Text?'
    description: >
      If set, the environment variable's value, otherwise, `none`.
  args:
    name:
      type: 'Text'
      description: >
        The name of the environment variable to get.
  example: |
    assert getenv("TERM") == "xterm-256color"
    assert getenv("not_a_variable") == none

print:
  short: print some text
  description: >
    Prints a message to the console (alias for say()).
  return:
    type: 'Void'
    description: >
      Nothing.
  args:
    text:
      type: 'Text'
      description: >
        The text to print.
    newline:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether or not to print a newline after the text.
  example: |
    print("Hello ", newline=no)
    print("world!")

say:
  short: print some text
  description: >
    Prints a message to the console.
  return:
    type: 'Void'
    description: >
      Nothing.
  args:
    text:
      type: 'Text'
      description: >
        The text to print.
    newline:
      type: 'Bool'
      default: 'yes'
      description: >
        Whether or not to print a newline after the text.
  example: |
    say("Hello ", newline=no)
    say("world!")

setenv:
  short: set an environment variable
  description: >
    Sets an environment variable.
  return:
    type: 'Void'
    description: >
      Nothing.
  args:
    name:
      type: 'Text'
      description: >
        The name of the environment variable to set.
    value:
      type: 'Text?'
      description: >
        The new value of the environment variable. If `none`, then the
        environment variable will be unset.
  example: |
    setenv("FOOBAR", "xyz")

sleep:
  short: wait for an interval
  description: >
    Pause execution for a given number of seconds.
  return:
    type: 'Void'
    description: >
      Nothing.
  args:
    seconds:
      type: 'Num'
      description: >
        How many seconds to sleep for.
  example: |
    sleep(1.5)

fail:
  short: abort the program
  description: >
    Prints a message to the console, aborts the program, and prints a stack trace.
  return:
    type: 'Abort'
    description: >
      Nothing, aborts the program.
  args:
    message:
      type: 'Text'
      description: >
        The error message to print.
  example: |
    fail("Oh no!")

USE_COLOR:
  short: whether to use colors
  type: Bool
  description: >
    Whether or not the console prefers ANSI color escape sequences in the output.