code / tomo

   1 ask:
   2   short: get user input
   3   description: >
   4     Gets a line of user input text with a prompt.
   5   note: >
   6     When a program is receiving input from a pipe or writing its
   7     output to a pipe, this flag (which is enabled by default) forces the program
   8     to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which
   9     circumvents the pipe. This means that `foo | ./tomo your-program | baz` will
  10     still show a visible prompt and read user input, despite the pipes. Setting
  11     this flag to `no` will mean that the prompt is written to `stdout` and input
  12     is read from `stdin`, even if those are pipes.
  13   return:
  14     type: 'Text?'
  15     description: >
  16       A line of user input text without a trailing newline, or empty text if
  17       something went wrong (e.g. the user hit `Ctrl-D`).
  18   args:
  19     prompt:
  20       type: 'Text'
  21       description: >
  22         The text to print as a prompt before getting the input.
  23     bold:
  24       type: 'Bool'
  25       default: 'yes'
  26       description: >
  27         Whether or not to print make the prompt appear bold on a console.
  28     force_tty:
  29       type: 'Bool'
  30       default: 'yes'
  31       description: >
  32         Whether or not to force the use of /dev/tty.
  33   example: |
  34     assert ask("What's your name? ") == "Arthur Dent"
  35 
  36 exit:
  37   short: exit the program
  38   description: >
  39     Exits the program with a given status and optionally prints a message.
  40   return:
  41     type: 'Abort'
  42     description: >
  43       This function never returns.
  44   args:
  45     message:
  46       type: 'Text?'
  47       default: 'none'
  48       description: >
  49         If nonempty, this message will be printed (with a newline) before
  50         exiting.
  51     status:
  52       type: 'Int32'
  53       default: 'Int32(1)'
  54       description: >
  55         The status code that the program with exit with.
  56   example: |
  57     exit("Goodbye forever!", Int32(1))
  58 
  59 at_cleanup:
  60   short: register a cleanup function
  61   description: >
  62     Register a function that runs at cleanup time for Tomo programs. Cleanup
  63     time happens when a program exits (see `atexit()` in C), or immediately
  64     before printing error messages in a call to `fail()`. This allows for
  65     terminal cleanup so error messages can be visible as the program shuts
  66     down.
  67   note: >
  68     Use this API very carefully, because errors that occur during cleanup
  69     functions may make it extremely hard to figure out what's going on. Cleanup
  70     functions should be designed to not error under any circumstances.
  71   args:
  72     fn:
  73       type: 'func()'
  74       description: >
  75         A function to run at cleanup time.
  76   return:
  77     type: 'Void'
  78     description: >
  79       Nothing.
  80   example: |
  81     at_cleanup(func()
  82         _ := (/tmp/file.txt).remove(ignore_missing=yes)
  83     )
  84 
  85 getenv:
  86   short: get an environment variable
  87   description: >
  88     Gets an environment variable.
  89   return:
  90     type: 'Text?'
  91     description: >
  92       If set, the environment variable's value, otherwise, `none`.
  93   args:
  94     name:
  95       type: 'Text'
  96       description: >
  97         The name of the environment variable to get.
  98   example: |
  99     assert getenv("TERM") == "xterm-256color"
 100     assert getenv("not_a_variable") == none
 101 
 102 print:
 103   short: print some text
 104   description: >
 105     Prints a message to the console (alias for say()).
 106   return:
 107     type: 'Void'
 108     description: >
 109       Nothing.
 110   args:
 111     text:
 112       type: 'Text'
 113       description: >
 114         The text to print.
 115     newline:
 116       type: 'Bool'
 117       default: 'yes'
 118       description: >
 119         Whether or not to print a newline after the text.
 120   example: |
 121     print("Hello ", newline=no)
 122     print("world!")
 123 
 124 say:
 125   short: print some text
 126   description: >
 127     Prints a message to the console.
 128   return:
 129     type: 'Void'
 130     description: >
 131       Nothing.
 132   args:
 133     text:
 134       type: 'Text'
 135       description: >
 136         The text to print.
 137     newline:
 138       type: 'Bool'
 139       default: 'yes'
 140       description: >
 141         Whether or not to print a newline after the text.
 142   example: |
 143     say("Hello ", newline=no)
 144     say("world!")
 145 
 146 setenv:
 147   short: set an environment variable
 148   description: >
 149     Sets an environment variable.
 150   return:
 151     type: 'Void'
 152     description: >
 153       Nothing.
 154   args:
 155     name:
 156       type: 'Text'
 157       description: >
 158         The name of the environment variable to set.
 159     value:
 160       type: 'Text?'
 161       description: >
 162         The new value of the environment variable. If `none`, then the
 163         environment variable will be unset.
 164   example: |
 165     setenv("FOOBAR", "xyz")
 166 
 167 sleep:
 168   short: wait for an interval
 169   description: >
 170     Pause execution for a given number of seconds.
 171   return:
 172     type: 'Void'
 173     description: >
 174       Nothing.
 175   args:
 176     seconds:
 177       type: 'Num'
 178       description: >
 179         How many seconds to sleep for.
 180   example: |
 181     sleep(1.5)
 182 
 183 fail:
 184   short: abort the program
 185   description: >
 186     Prints a message to the console, aborts the program, and prints a stack trace.
 187   return:
 188     type: 'Abort'
 189     description: >
 190       Nothing, aborts the program.
 191   args:
 192     message:
 193       type: 'Text'
 194       description: >
 195         The error message to print.
 196   example: |
 197     fail("Oh no!")
 198 
 199 USE_COLOR:
 200   short: whether to use colors
 201   type: Bool
 202   description: >
 203     Whether or not the console prefers ANSI color escape sequences in the output.