1 % API
   2 
   3 # Builtins
   4 ## USE_COLOR
   5 
   6 ```tomo
   7 USE_COLOR : Bool
   8 ```
   9 
  10 Whether or not the console prefers ANSI color escape sequences in the output.
  11 
  12 ## ask
  13 
  14 ```tomo
  15 ask : func(prompt: Text, bold: Bool = yes, force_tty: Bool = yes -> Text?)
  16 ```
  17 
  18 Gets a line of user input text with a prompt.
  19 
  20 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.
  21 
  22 Argument | Type | Description | Default
  23 ---------|------|-------------|---------
  24 prompt | `Text` | The text to print as a prompt before getting the input.  | -
  25 bold | `Bool` | Whether or not to print make the prompt appear bold on a console.  | `yes`
  26 force_tty | `Bool` | Whether or not to force the use of /dev/tty.  | `yes`
  27 
  28 **Return:** A line of user input text without a trailing newline, or empty text if something went wrong (e.g. the user hit `Ctrl-D`).
  29 
  30 
  31 **Example:**
  32 ```tomo
  33 assert ask("What's your name? ") == "Arthur Dent"
  34 
  35 ```
  36 ## at_cleanup
  37 
  38 ```tomo
  39 at_cleanup : func(fn: func() -> Void)
  40 ```
  41 
  42 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.
  43 
  44 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.
  45 
  46 Argument | Type | Description | Default
  47 ---------|------|-------------|---------
  48 fn | `func()` | A function to run at cleanup time.  | -
  49 
  50 **Return:** Nothing.
  51 
  52 
  53 **Example:**
  54 ```tomo
  55 at_cleanup(func()
  56     _ := (/tmp/file.txt).remove(ignore_missing=yes)
  57 )
  58 
  59 ```
  60 ## exit
  61 
  62 ```tomo
  63 exit : func(message: Text? = none, status: Int32 = Int32(1) -> Abort)
  64 ```
  65 
  66 Exits the program with a given status and optionally prints a message.
  67 
  68 Argument | Type | Description | Default
  69 ---------|------|-------------|---------
  70 message | `Text?` | If nonempty, this message will be printed (with a newline) before exiting.  | `none`
  71 status | `Int32` | The status code that the program with exit with.  | `Int32(1)`
  72 
  73 **Return:** This function never returns.
  74 
  75 
  76 **Example:**
  77 ```tomo
  78 exit("Goodbye forever!", Int32(1))
  79 
  80 ```
  81 ## fail
  82 
  83 ```tomo
  84 fail : func(message: Text -> Abort)
  85 ```
  86 
  87 Prints a message to the console, aborts the program, and prints a stack trace.
  88 
  89 Argument | Type | Description | Default
  90 ---------|------|-------------|---------
  91 message | `Text` | The error message to print.  | -
  92 
  93 **Return:** Nothing, aborts the program.
  94 
  95 
  96 **Example:**
  97 ```tomo
  98 fail("Oh no!")
  99 
 100 ```
 101 ## getenv
 102 
 103 ```tomo
 104 getenv : func(name: Text -> Text?)
 105 ```
 106 
 107 Gets an environment variable.
 108 
 109 Argument | Type | Description | Default
 110 ---------|------|-------------|---------
 111 name | `Text` | The name of the environment variable to get.  | -
 112 
 113 **Return:** If set, the environment variable's value, otherwise, `none`.
 114 
 115 
 116 **Example:**
 117 ```tomo
 118 assert getenv("TERM") == "xterm-256color"
 119 assert getenv("not_a_variable") == none
 120 
 121 ```
 122 ## print
 123 
 124 ```tomo
 125 print : func(text: Text, newline: Bool = yes -> Void)
 126 ```
 127 
 128 Prints a message to the console (alias for say()).
 129 
 130 Argument | Type | Description | Default
 131 ---------|------|-------------|---------
 132 text | `Text` | The text to print.  | -
 133 newline | `Bool` | Whether or not to print a newline after the text.  | `yes`
 134 
 135 **Return:** Nothing.
 136 
 137 
 138 **Example:**
 139 ```tomo
 140 print("Hello ", newline=no)
 141 print("world!")
 142 
 143 ```
 144 ## say
 145 
 146 ```tomo
 147 say : func(text: Text, newline: Bool = yes -> Void)
 148 ```
 149 
 150 Prints a message to the console.
 151 
 152 Argument | Type | Description | Default
 153 ---------|------|-------------|---------
 154 text | `Text` | The text to print.  | -
 155 newline | `Bool` | Whether or not to print a newline after the text.  | `yes`
 156 
 157 **Return:** Nothing.
 158 
 159 
 160 **Example:**
 161 ```tomo
 162 say("Hello ", newline=no)
 163 say("world!")
 164 
 165 ```
 166 ## setenv
 167 
 168 ```tomo
 169 setenv : func(name: Text, value: Text? -> Void)
 170 ```
 171 
 172 Sets an environment variable.
 173 
 174 Argument | Type | Description | Default
 175 ---------|------|-------------|---------
 176 name | `Text` | The name of the environment variable to set.  | -
 177 value | `Text?` | The new value of the environment variable. If `none`, then the environment variable will be unset.  | -
 178 
 179 **Return:** Nothing.
 180 
 181 
 182 **Example:**
 183 ```tomo
 184 setenv("FOOBAR", "xyz")
 185 
 186 ```
 187 ## sleep
 188 
 189 ```tomo
 190 sleep : func(seconds: Num -> Void)
 191 ```
 192 
 193 Pause execution for a given number of seconds.
 194 
 195 Argument | Type | Description | Default
 196 ---------|------|-------------|---------
 197 seconds | `Num` | How many seconds to sleep for.  | -
 198 
 199 **Return:** Nothing.
 200 
 201 
 202 **Example:**
 203 ```tomo
 204 sleep(1.5)
 205 
 206 ```