Make API documentation into YAML files and autogenerate markdown files

and manpages from those.

1 files changed, 183 insertions, 0 deletions

diff --git a/api/builtins.md b/api/builtins.md
new file mode 100644
index 00000000..671849c3
--- /dev/null
+++ b/api/builtins.md
@@ -0,0 +1,183 @@
+% API
+
+# Builtins
+## USE_COLOR
+
+```tomo
+USE_COLOR : Bool
+```
+
+Whether or not the console prefers ANSI color escape sequences in the output.
+
+## ask
+
+```tomo
+ask : func(prompt: Text, bold: Bool = yes, force_tty: Bool = yes -> Text?)
+```
+
+Gets a line of user input text with a prompt.
+
+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.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+prompt | `Text` | The text to print as a prompt before getting the input.  | 
+bold | `Bool` | Whether or not to print make the prompt appear bold on a console.  | **Default:** `yes`
+force_tty | `Bool` | Whether or not to force the use of /dev/tty.  | **Default:** `yes`
+
+**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`).
+
+
+**Example:**
+```tomo
+>> ask("What's your name? ")
+= "Arthur Dent"
+
+```
+## exit
+
+```tomo
+exit : func(message: Text? = !Text, status: Int32 = Int32(1) -> Void)
+```
+
+Exits the program with a given status and optionally prints a message.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+message | `Text?` | If nonempty, this message will be printed (with a newline) before exiting.  | **Default:** `!Text`
+status | `Int32` | The status code that the program with exit with.  | **Default:** `Int32(1)`
+
+**Return:** This function never returns.
+
+
+**Example:**
+```tomo
+exit(status=1, "Goodbye forever!")
+
+```
+## fail
+
+```tomo
+fail : func(message: Text -> Abort)
+```
+
+Prints a message to the console, aborts the program, and prints a stack trace.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+message | `Text` | The error message to print.  | 
+
+**Return:** Nothing, aborts the program.
+
+
+**Example:**
+```tomo
+fail("Oh no!")
+
+```
+## getenv
+
+```tomo
+getenv : func(name: Text -> Text?)
+```
+
+Gets an environment variable.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+name | `Text` | The name of the environment variable to get.  | 
+
+**Return:** If set, the environment variable's value, otherwise, `none`.
+
+
+**Example:**
+```tomo
+>> getenv("TERM")
+= "xterm-256color"?
+
+```
+## print
+
+```tomo
+print : func(text: Text, newline: Bool = yes -> Void)
+```
+
+Prints a message to the console (alias for [`say`](#say)).
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+text | `Text` | The text to print.  | 
+newline | `Bool` | Whether or not to print a newline after the text.  | **Default:** `yes`
+
+**Return:** Nothing.
+
+
+**Example:**
+```tomo
+print("Hello ", newline=no)
+print("world!")
+
+```
+## say
+
+```tomo
+say : func(text: Text, newline: Bool = yes -> Void)
+```
+
+Prints a message to the console.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+text | `Text` | The text to print.  | 
+newline | `Bool` | Whether or not to print a newline after the text.  | **Default:** `yes`
+
+**Return:** Nothing.
+
+
+**Example:**
+```tomo
+say("Hello ", newline=no)
+say("world!")
+
+```
+## setenv
+
+```tomo
+setenv : func(name: Text, value: Text -> Void)
+```
+
+Sets an environment variable.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+name | `Text` | The name of the environment variable to set.  | 
+value | `Text` | The new value of the environment variable.  | 
+
+**Return:** Nothing.
+
+
+**Example:**
+```tomo
+setenv("FOOBAR", "xyz")
+
+```
+## sleep
+
+```tomo
+sleep : func(seconds: Num -> Void)
+```
+
+Pause execution for a given number of seconds.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+seconds | `Num` | How many seconds to sleep for.  | 
+
+**Return:** Nothing.
+
+
+**Example:**
+```tomo
+sleep(1.5)
+
+```