context-large.txt

context/common-rules.md
---
# Important rules when writing Risor code
- Use two spaces to indent code
- No `var` keyword for variables (use `:=`)
- No `??` operator for null coalescing (use `coalesce()` function)
- Module imports don't use quotes. Use `import math` and not not `import "math"`
- Use single quotes for string interpolation: `'Hello, {name}'`
- If-else and switch are expressions that return values
- String interpolation with single quotes only supports simple variable substitution (`'{variable}'`). It does not support formatting specifications inside the curly braces like Python's f-strings. To format values, use the `fmt.sprintf()` function separately and concatenate the results
- ^ is not a valid power operator in Risor. Use math.pow() function instead
- Use os.stdin.input() to read input from the user
- Risor doesn't have while to create loops. Always use for and range.
- Risor doesn't have __main__ or __file__ globals
- Risor doesn't support variadic arguments when calling or defining functions
- Lists in Risor behave very similarly to lists in Python. Methods and indexing
on lists are the primary way to interact with these objects. A list can store
objects of any types, including a mix of types in one list.

```go
>>> l := ["a", 1, 2]
["a", 1, 2]
>>> l.append("tail")
["a", 1, 2, "tail"]
```
- Reserved keywords:
  - func
  - import
  - return
  - if
  - for
  - range
  - spawn
  - from

Always follow the above rules.


---
context/docgen.md
---
## Documenting Risor function, classes and methods

```go
// Description of the function
// This can span multiple lines
//
// Parameters:
// - param1: Description of first parameter
// - param2: Description of second parameter
//
// Returns: Description of what is returned
```

### Class or Function Annotations

The tool looks for special annotation comments:

- `@object.class` - Marks a class declaration
- `@object.method` - Marks a class method
- `@global.function` - Marks a global function

## Example

Input Risor file:

```go
// Prints a string
//
// Parameters:
// - msg: string to print
//
// @global.function
func print(msg) {
}

// @object.class
Calculator := {
  // Adds two numbers
  //
  // Parameters:
  // - a: First number
  // - b: Second number
  //
  // Returns: Sum of a and b
  // @object.method
  add = func(a, b) {
    return a + b
  }
}
```

## Important

* Ignore function names starting with _ or __


---
context/docs/README.md
---
This directory contains Risor documentation from https://github.com/risor-io/risor-site/tree/main/pages/docs.


---
context/docs/builtins.mdx
---
import { Callout } from 'nextra/components';

# Built-in Functions

Risor includes this set of default built-in functions. The set of available
built-ins is easily customizable, depending on the goals for your project.

### all

```go filename="Function signature"
all(container) bool
```

Returns `true` if all objects in the given container are "truthy".

```go copy filename="Example"
>>> all([true, 1, "ok"])
true
>>> all([true, 0, "ok"])
false
```

### any

```go filename="Function signature"
any(container) bool
```

Returns `true` if any of the objects in the given container are "truthy".

```go copy filename="Example"
>>> any([false, 0, "ok"])
true
>>> any([false, 0, ""])
false
```

### assert

```go filename="Function signature"
assert(object, message)
```

Generates an error if `x` is "falsy". If a message is provided, it is used as
the assertion error message.

```go copy filename="Example"
>>> assert(1 == 1)                 // no effect
>>> assert(1 == 1, "check failed") // no effect
>>> assert(1 == 2, "check failed") // raises error
check failed
>>> assert(1 == 2)                 // raises error
assertion failed
```

### bool

```go filename="Function signature"
bool(object) bool
```

Returns `true` or `false` depending on whether the object is considered "truthy".
Container types including lists, maps, sets, and strings evaluate to `false` when
empty and `true` otherwise.

```go copy filename="Example"
>>> bool(1)
true
>>> bool(0)
false
>>> bool([1])
true
>>> bool([])
false
```

### buffer

```go filename="Function signature"
buffer(object) buffer
```

Returns a Buffer object that wraps a Go `bytes.Buffer`.

```go copy filename="Example"
>>> buffer(5)
buffer("\x00\x00\x00\x00\x00")
>>> buffer(byte_slice([65, 66, 67]))
buffer("ABC")
>>> string(buffer(byte_slice([65, 66, 67])))
"ABC"
```

<Callout type="info" emoji="ℹ️">
  The Buffer type interoperates easily with Strings and ByteSlices. The Buffer
  Go type implements [io.ReadWriter](https://pkg.go.dev/io#ReadWriter)
  which means it can be provided to any Go function that accepts an
  `io.Reader` or `io.Writer`.
</Callout>

### byte_slice

```go filename="Function signature"
byte_slice(object) byte_slice
```

Creates a new slice of bytes, which wraps the Go type `[]byte`. If a single
argument is provided, it is used as the initial capacity of the slice. If a
list of values is provided, the slice is initialized with those values.

```go copy filename="Example"
>>> byte_slice()
byte_slice("")
>>> byte_slice(5)
byte_slice("\x00\x00\x00\x00\x00")
>>> byte_slice([1, 2, 3])
byte_slice("\x01\x02\x03")
>>> byte_slice([65, 66, 67])
byte_slice("ABC")
>>> byte_slice([65]) + byte_slice([66, 67])
byte_slice("ABC")
>>> string(byte_slice([65, 66, 67]))
"ABC"
```

### byte

```go filename="Function signature"
byte(object) byte
```

Returns a Byte object that wraps a Go `byte`. The Byte type interoperates
seamlessly with Ints and Floats.

```go copy filename="Example"
>>> byte()
0
>>> byte(3)
3
>>> byte("3")
3
>>> byte(3) == 3
true
>>> byte(3) + 5.5
8.5
```

### call

```go filename="Function signature"
call(function, ...args object) object
```

Calls the function with given arguments. This is primarily useful in pipe
expressions when a function is being passed through the pipe as a variable.

```go copy filename="Example"
>>> func inc(x) { x + 1 }
>>> call(inc, 99)
100
>>> inc | call(41)
42
```

### cat

```go filename="Function signature"
cat(path string, ...paths string) string
```

Similar to the `cat` command in Unix, this function concatenates the contents
of the given file path(s) and returns the result as a string.

Assuming the following file exists:

```text filename="names.txt"
alice
blake
```

```go copy filename="Example"
>>> cat("names.txt")
"alice\nblake\n"
```

### cd

```go filename="Function signature"
cd(string)
```

Changes the current working directory to the given path.

```go copy filename="Example"
>>> cd("/tmp")
>>> os.getwd()
"/tmp"
```

### chan

```go filename="Function signature"
chan(capacity int = 0) chan
```

Creates a new channel with the given capacity. If unspecified, the capacity
defaults to 0. Channels are used to send and receive Risor objects between
goroutines. The underlying Go equivalent is `chan object.Object`. This means
any Risor object can be sent and received over a channel. Currently the Risor
`select` statement does not support channels, however it may in the future.

```risor copy filename="Example"
>>> c := chan(8)
>>> c <- "test"
>>> <-c
"test"
```

_New in Risor v1.4.0_.

### chr

```go filename="Function signature"
chr(int) string
```

Converts an Int to the corresponding unicode rune, which is returned as a String.
The `ord` built-in performs the inverse transformation.

```go copy filename="Example"
>>> chr(8364)
"€"
>>> chr(97)
"a"
```

### chunk

```go filename="Function signature"
chunk(container, size int) list
```

Returns a list of chunks of the given container, where each chunk is a list of
the given size. If the container is not evenly divisible by the size, the last
chunk will contain the remaining elements.

```go copy filename="Example"
>>> chunk([1, 2, 3, 4, 5], 2)
[[1, 2], [3, 4], [5]]
>>> chunk([1, 2, 3, 4, 5], 3)
[[1, 2, 3], [4, 5]]
>>> chunk([1, 2, 3, 4, 5], 4)
[[1, 2, 3, 4], [5]]
>>> chunk([1, 2, 3, 4, 5], 5)
[[1, 2, 3, 4, 5]]
```

### close

```go filename="Function signature"
close(channel)
```

Closes the given channel. This directly corresponds to the Go `close` function.
If called on an already closed channel, an error is raised.

```risor copy filename="Example"
c := chan()

go func() {
    c <- 42
    close(c)
}()

for _, v := range c {
    print(v)
}
```

### coalesce

```go filename="Function signature"
coalesce(...objects) object
```

Returns the first non-nil object in the given list of arguments. If no
arguments are provided, or all arguments are `nil`, the result is `nil`.

```risor copy filename="Example"
>>> coalesce(nil, 1, 2, 3)
1
>>> coalesce(nil, nil, nil) # returns nil
>>> coalesce()              # returns nil
```

### cp

```go filename="Function signature"
cp(src_path string, dst_path string)
```

Copies the contents of the source file to the destination file. If the
destination file already exists, it is overwritten.

```go copy filename="Example"
>>> cp("foo.txt", "bar.txt")
```

### decode

```go filename="Function signature"
decode(object, codec_name string) object
```

Decodes the given object using the specified codec. The codec_name is a string
that may be one of the following values:

- `base64`
- `base32`
- `gzip`
- `hex`
- `json`
- `csv`
- `urlquery`

```go copy filename="Example"
>>> decode("616263", "hex")
byte_slice("abc")
>>> decode("YWJj", "base64")
byte_slice("abc")
>>> decode("a,b,c\n", "csv")
[["a", "b", "c"]]
```

_See additional notes about codecs in the [encode](#encode) section below._

### delete

```go filename="Function signature"
delete(map, key string)
```

Deletes the item with the specified key from the map. This operation has no
effect if the key is not present in the map.

```go copy filename="Example"
>>> m := {one: 1, two: 2}
{"one": 1, "two": 2}
>>> delete(m, "one")
{"two": 2}
>>> delete(m, "foo")
{"two": 2}
```

### encode

```go filename="Function signature"
encode(object, codec_name string) object
```

Encodes the given object using the specified codec. The codec_name is a string
that may be one of the following values:

- `base64`
- `base32`
- `gzip`
- `hex`
- `json`
- `csv`
- `urlquery`

```go copy filename="Example"
>>> encode("abc", "hex")
"616263"
>>> encode("abc", "base64")
"YWJj"
>>> encode([["a", "b", "c"]], "csv")
"a,b,c\n"
```

`base64`, `base32`, and `hex` codecs operate on byte slices or types that can be
automatically converted to a byte slice, such as strings. Other codecs may accept
different types.

<Callout type="info" emoji="ℹ️">
  Additional codecs may be registered by calling the Go function
  `builtins.RegisterCodec`
</Callout>

_gzip encoding added in Risor v1.5.0_.

### error

```go filename="Function signature"
error(message string)
```

Raises an Error containing the given message. A [try](#try) call can be used to
catch the error and handle it. Otherwise, the call stack unwinds and error
stops execution of the program.

```go copy filename="Example"
>>> error("kaboom")
kaboom
```

### fetch

```go filename="Function signature"
fetch(url string, opts map) http.response
```

Fetches the content of the given URL and returns an `http.response` object. The
response object provides access to the HTTP status code, headers, and body.

The following options are supported:

| Name    | Type                 | Description                                            |
| ------- | -------------------- | ------------------------------------------------------ |
| method  | string               | The HTTP method to use.                                |
| headers | map                  | The headers to send with the request.                  |
| params  | map                  | The query parameters to send with the request.         |
| body    | byte_slice or reader | The request body.                                      |
| timeout | int                  | Request timeout in milliseconds.                       |
| data    | object               | Object to marshal as JSON and send in the request body |

```go copy filename="Example"
>>> r := fetch("https://httpbin.org/get")
>>> r.status_code
200
>>> r.header
{"Connection": ["keep-alive"], "Content-Length": ["14"], "Content-Type": ["text/plain"], "Date": ["Mon, 15 Jan 2024 00:06:56 GMT"], "Server": ["nginx/1.25.1"], "Vary": ["Origin"]}
>>> r.text()
"143.89.131.113"
```

Visit the [http.response documentation](/docs/modules/http#response) for more information
about the response object and its attributes.

### float_slice

```go filename="Function signature"
float_slice(object) float_slice
```

Creates a new slice of floating point values, which wraps the Go type `[]float64`.
If a single argument is provided, it is used as the initial capacity of the slice.
If a list of values is provided, the slice is initialized with those values.

```go copy filename="Example"
>>> float_slice()
float_slice([])
>>> float_slice(5)
float_slice([0 0 0 0 0])
>>> float_slice([1.1, 2.2, 3.3])
float_slice([1.1 2.2 3.3])
>>> float_slice([1.1, 2.2, 3.3])[0]
1.1
```

### float

```go filename="Function signature"
float(object) float
```

Converts a String or Int object to a Float. An error is generated if the
operation fails.

```go copy filename="Example"
>>> float()
0
>>> float("4.4")
4.4
```

### getattr

```go filename="Function signature"
getattr(object, name string, default_value object) object
```

Returns the named attribute from the object, or the default value if the
attribute does not exist. The returned attribute is always a Risor object,
which may be a function. This is similar to
[getattr](https://docs.python.org/3/library/functions.html#getattr) in Python.

```go copy filename="Example"
>>> l := [1,2,3]
[1, 2, 3]
>>> append := getattr(l, "append")
builtin(list.append)
>>> append(4)
[1, 2, 3, 4]
>>> getattr(l, "unknown", "that doesn't exist")
"that doesn't exist"
```

### getenv

```go filename="Function signature"
getenv(name string) string
```

Returns the value of the environment variable with the given name. If the
variable is not set, an empty string is returned.

```go copy filename="Example"
>>> getenv("HOME")
"/home/username"
```

### hash

```go filename="Function signature"
hash(b byte_slice, algorithm string) byte_slice
```

Hashes the given byte_slice b using the specified algorithm. If not provided,
algorithm defaults to "sha256".

```go copy filename="Example"
>>> hash("abc")
byte_slice("\xbax\x16\xbf\x8f\x01\xcf\xeaAA@\xde]\xae\"#\xb0\x03a\xa3\x96\x17z\x9c\xb4\x10\xffa\xf2\x00\x15\xad")
>>> hash("a", "md5")
byte_slice("\f\xc1u\xb9\xc0\xf1\xb6\xa81Ù\xe2iw&a")
```

Available algorithms:

- `md5`
- `sha1`
- `sha256`
- `sha512`

### int

```go filename="Function signature"
int(object) int
```

Converts a String or Float to an Int. An error is generated if the operation
fails.

```go copy filename="Example"
>>> int(4.4)
4
>>> int("123")
123
```

### is_hashable

```go filename="Function signature"
is_hashable(object) bool
```

Returns `true` if the object is hashable, otherwise returns `false`. A Risor
object is hashable if it implements the `object.Hashable` interface, which is
defined in [this file](https://github.com/risor-io/risor/blob/main/object/object.go).

Hashable objects may be stored as elements of a Risor set.

```go copy filename="Example"
>>> is_hashable("abc")
true
>>> is_hashable([1, 2, 3])
false
```

### iter

```go filename="Function signature"
iter(container) iterator
```

Returns an iterator for the given container object. This can be used to iterate
through items in a for loop or interacted with more directly. The returned
iterator has `next()` and `entry()` methods which are used to move forward and
to retrieve the current entry, respectively.

```go copy filename="Example"
>>> s := {"a", "b", "c"}
>>> iterator := iter(s)
>>> iterator.next()
"a"
>>> iterator.next()
"b"
>>> iterator.entry()
iter_entry("b", true)
>>> iterator.entry().key
"b"
>>> iterator.entry().value
true
```

### jmespath

```go filename="Function signature"
jmespath(data object, expression string) object
```

Queries data using the given [JMESPath](https://jmespath.org/) expression. Note
the data is provided as the first argument which makes it useful in pipe
expressions.

```go copy filename="Example"
>>> jmespath({"count": 42, "name": "foo"}, "count")
42
>>> [{"name": "a"}, {"name": "b"}] | jmespath("[].name")
["a", "b"]
```

<Callout type="info" emoji="ℹ️">
  The `jmespath` built-in is included in the Risor CLI by default. However if
  Risor is being used as a library, the `jmespath` module must be imported
  explicitly.
</Callout>

### keys

```go filename="Function signature"
keys(container) list
```

Returns a list of all keys for items in the given map or list container.

```go copy filename="Example"
>>> m := {one: 1, two: 2}
{"one": 1, "two": 2}
>>> keys(m)
["one", "two"]
```

### len

```go filename="Function signature"
len(container) int
```

Returns the size of the given container. Container types include:

- `String`
- `List`
- `Map`
- `Set`
- `FloatSlice`
- `ByteSlice`

```go copy filename="Example"
>>> len("ab")        // string length
2
>>> len([1,2,3])     // list length
3
>>> len({foo:"bar"}) // map length
1
>>> len({1,2,3,4})   // set length
4
```

<Callout type="info" emoji="ℹ️">
  Note that for String types, the length is the _number of underlying runes_ in
  the string, not the number of bytes. This is subtly different than taking the
  `len(s)` of a string in Go, which returns the number of bytes. Conceptually,
  the approach Risor takes is that a String is a container for
  [runes](https://go.dev/blog/strings).
</Callout>

### list

```go filename="Function signature"
list(container) list
```

Returns a new list populated with items from the given container. If a list is
provided, a shallow copy of the list is returned. It is also commonly used to
convert a set to a list.

```go copy filename="Example"
>>> s := {"a", "b", "c"}
{"a", "b", "c"}
>>> list(s)
["a", "b", "c"]
```

### ls

```go filename="Function signature"
ls(path string) list
```

Lists the contents of the specified directory. If a directory is not provided,
the current working directory is used. The returned list contains one `DirEntry`
object for each file or directory in the specified directory.

```go copy filename="Example"
>>> ls()
[dir_entry(name=file1.txt, type=regular), dir_entry(name=logs, type=dir)]
>>> ls("logs")
[dir_entry(name=logs.txt, type=regular)]
```

### make

```go filename="Function signature"
make(object object, capacity int = 0) object
```

Most Risor programs do not need to use `make` explicitly, however it can be
useful when you would like to specify the underlying capacity of a container.
This wraps the Go `make` function.

The `object` argument must be one of the following:

- a `list`, `map`, or `set` object.
- a built-in function, one of: `chan`, `list`, `map`, or `set`.

This object is only used to signal which type of object is being created. The
capacity is specified by the `capacity` argument, which defaults to 0 if not
provided.

```risor copy filename="Example"
>>> make(list, 10)
[] # empty list, with underlying slice of capacity 10
>>> make([], 10)
[] # empty list, with underlying slice of capacity 10
```

_New in Risor v1.4.0_.

### map

```go filename="Function signature"
map(container) map
```

Returns a new map which is populated with the items from the given container
if one is provided. This behaves similarly to `dict` in Python.

```go copy filename="Example"
>>> map()
{}
>>> map([["k1", 1], ["k2", 2]])
{"k1": 1, "k2": 2}
>>> map({"a", "b", "c"}) // converts a set to a map
{"a": true, "b": true, "c": true}
```

### nslookup

```go filename="Function signature"
nslookup(name string, query_type string = "HOST", resolver_addr string = "")
```

Look up the given domain name using the specified query type (default "HOST") and resolver
address (default "" for system default).

```go copy filename="Example"
>>> nslookup("google.com")
["172.253.115.138", "172.253.115.100", "172.253.115.139", "172.253.115.113", "172.253.115.101", "172.253.115.102", "2607:f8b0:4004:c08::8b", "2607:f8b0:4004:c08::71", "2607:f8b0:4004:c08::8a", "2607:f8b0:4004:c08::65"]
```

### ord

```go filename="Function signature"
ord(string) int
```

Converts a unicode character to the corresponding Int value. The `chr` built-in
performs the inverse transformation. An error is generated if a multi-rune string is
provided.

```go copy filename="Example"
>>> ord("€")
8364
>>> ord("a")
97
>>> chr(ord("€"))
"€"
```

### print

```go filename="Function signature"
print(args ...object)
```

Prints the provided objects to stdout after converting them to their String
representations. Spaces are inserted between each object and a trailing newline
is output. This is a wrapper around `fmt.Println`.

```go copy filename="Example"
>>> print(42, "is the answer")
42 is the answer
```

### printf

```go filename="Function signature"
printf(format string, args ...object)
```

Printf wraps `fmt.Printf` in order to print the formatted string and arguments
to stdout. In the Risor REPL you will currently not see the `printf` output
unless the string ends in a newline character.

```go copy filename="Example"
>>> printf("name: %s age: %d\n", "joe", 32)
name: joe age: 32
```

### reversed

```go filename="Function signature"
reversed(list) list
```

Returns a new list which is a reversed copy of the provided list.

```go copy filename="Example"
>>> l := ["a", "b", "c"]
["a", "b", "c"]
>>> reversed(l)
["c", "b", "a"]
>>> l
["a", "b", "c"]
```

### set

```go filename="Function signature"
set(container) set
```

Returns a new set containing the items from the given container object.

```go copy filename="Example"
>>> set("aabbcc")
{"a", "b", "c"}
>>> set([4,4,5])
{4, 5}
>>> set({one:1, two:2})
{"one", "two"}
```

### setenv

```go filename="Function signature"
setenv(name, value string)
```

Sets the value of the environment variable with the given name to the provided
value. If the variable does not exist, it is created.

```go copy filename="Example"
>>> setenv("FOO", "bar")
>>> getenv("FOO")
"bar"
```

### sorted

```go filename="Function signature"
sorted(container) list
```

Returns a sorted list of items from the given container object.

```go copy filename="Example"
>>> sorted("cba")
["a", "b", "c"]
>>> sorted([10, 3, -5])
[-5, 3, 10]
```

### spawn

```go filename="Function signature"
spawn(function, args ...object) thread
```

Spawns a new goroutine and executes the given function in that goroutine. The
function is passed the remaining arguments. Returns a Risor thread object that
can be used to wait for the goroutine to finish and retrieve its return value.

```go copy filename="Example"
>>> func addone(x) { return x + 1 }
>>> t := spawn(addone, 1)
>>> t.wait()
2
```

When using Risor as a library, this level of concurrency is not available
by default. To enable it, pass the `risor.WithConcurrency()` option when
initializing a Risor VM.

_New in Risor v1.4.0_.

### sprintf

```go filename="Function signature"
sprintf(format string, args ...object) string
```

Wraps `fmt.Sprintf` to format the string with the provided arguments. Risor
objects are converted to their corresponding Go types before being passed to
`fmt.Sprintf`.

```go copy filename="Example"
>>> sprintf("name: %s age: %d", "fred", 18)
"name: fred age: 18"
>>> sprintf("%v", [1, "a", 3.3])
"[1 a 3.3]"
```

### string

```go filename="Function signature"
string(object) string
```

Returns a string representation of the given Risor object.

```go copy filename="Example"
>>> string({one:1, two:2})
"{\"one\": 1, \"two\": 2}"
>>> string(4.4)
"4.4"
>>> string([1,2,3])
"[1, 2, 3]"
```

### try

```go filename="Function signature"
try(args ...object) object
```

Accepts one or more functions which are executed in order until one of them
doesn't raise an error and returns that functions return value. If any
non-callable object is reached in the provided arguments, that object is
returned immediately. Otherwise, if all functions raise errors, `nil` is returned.

```go copy filename="Example"
>>> func kaboom() { error("kaboom!") }
>>> try(kaboom)                                      // returns nil
>>> try(kaboom, func() { error("this failed too") }) // returns nil
>>> try(kaboom, "fallback")                          // returns "fallback"
"fallback"
>>> try(42)
42
>>> try(func() { 42 })
42
```

If any function after the first accepts an argument, any error raised by the
previous function is passed to the next function as its first argument.

The example below prints `caught error: kaboom` and then returns the value 33.

```risor copy filename="Example"
try(func() {
    error("kaboom")
}, func(err) {
    print("caught error:", err)
    return 33
})
```

### type

```go filename="Function signature"
type(object) string
```

Returns the type name of the given object as a String.

```go copy filename="Example"
>>> type(1)
"int"
>>> type(2.2)
"float"
>>> type("hi")
"string"
>>> type([])
"list"
>>> type({})
"map"
>>> type({1,2,3})
"set"
```

### unsetenv

```go filename="Function signature"
unsetenv(name string)
```

Removes the environment variable with the given name.

```go copy filename="Example"
>>> setenv("FOO", "bar")
>>> getenv("FOO")
"bar"
>>> unsetenv("FOO")
>>> getenv("FOO")
""
```


---
context/docs/syntax.mdx
---
# Syntax

The overall idea for Risor syntax is that it is like Go, but aims to be more
concise and expressive for scripting. Variables are dynamically typed and all
Risor object types implement an `object.Object` interface defined in Go.

### Variable Declarations

Variables are declared using the := operator. Unlike in Go, all variables
are dynamically typed.

```risor copy
// Declare a variable `x` and assign the integer value 10
x := 10

// Declare a variable `y` and assign the string value "hello"
y := "hello"

// Declare a variable `array` and assign an array of integers
array := [1, 2, 3]
```

Constant declarations are also supported:

```risor copy
const url = "https://example.com"
```

### Variable Assignment

Existing variables can be set using the = operator:

```risor copy
// Declare `x`
x := 10

// Update `x` to 20
x = 20
```

### Functions

Functions in Risor are declared using the `func` keyword. Type declarations are
not supported.

```risor copy
func last(data) {
    if len(data) == 0 {
        return nil
    }
    return data[-1]
}
```

Default parameter values are supported, with allowed types including strings,
integers, floats, and booleans:

```risor copy
func greet(name='world') {
    return 'Hello, ' + name
}
```

Unlike in Go, functions can only return a single value. You can, however, return
a list and unpack it:

```risor copy
func swap(a, b) {
    return [b, a]
}

x, y := swap(10, 20)
print(x, y)  // 20 10
```

Functions may be assigned to a variable and passed as values:

```risor copy
add := func(a, b) {
    return a + b
}

result := add(10, 20) // 30
```

### Control Flow

Risor supports most forms of control flow present in Go.

```risor copy
x := 10
threshold := 5
if x > threshold {
    print("greater")
} else if x == threshold {
    print("equal")
} else {
    print("lesser")
}
```

One difference with Risor is that if-else and switch are expressions in Risor,
meaning they evaluate to a value.

```risor copy
x := if 10 > 5 {
    "greater"
} else {
    "lesser"
}

print(x)  # "greater"
```

```risor copy
name := "Alice"
x := switch name {
    case "Joe":
        "Hello, Joe"
    default:
        "Hello, stranger"
}
print(x)  # "Hello, Joe"
```

Ternary expressions are supported:

```risor copy
x := 10 > 5 ? 1 : 0
print(x) // 1
```

### Loops

Risor supports for loops and range loops in the same way as Go.

```risor copy
for i := 0; i < 5; i++ {
    print(i)
}
```

```risor copy
i := 0
for i < 5 {
    print(i)
    i++
}
```

```risor copy
array := [1, 2, 3]
for i, value := range array {
    print(i, value)
}
```

```risor copy
for {
    print("infinite loop")
    time.sleep(1)
}
```

`break` and `continue` keywords are also supported.

```risor copy
for i := 0; i < 10; i++ {
    if i == 5 {
        break
    }
    print(i)
}
```

```risor copy
for i := 0; i < 10; i++ {
    if i == 5 {
        continue
    }
    print(i)
}
```

### Errors

Risor errors are similar to exceptions in languages like Python and Javascript.
This makes Risor more concise and suitable for scripts, as compared to Go. A
built-in `try` function is provided to attempt an operation and fallback to a
default value if it fails. `try` accepts any number of functions, and the first
one that does not raise an error has its result returned. If a non-function value
is reached, it is returned immediately.

```risor copy
result := try(func() { error("kaboom") }, "default value")
print(result)  # "default value"
```

Errors can be raised using the `error` function:

```risor copy
func divide(a, b) {
    if b == 0 {
        error("bad idea: division by zero")
    }
    return a / b
}
```

Also see the [Try-Catch Error Handling](syntax#try-catch-error-handling) section
for more information.

### Pipe Expressions

Risor supports pipe expressions, which allow you to chain function calls
together. The pipe operator `|` takes the result of the expression on its left
and passes it as the first argument to the function on its right.

```risor copy
result := "hello" | strings.to_upper
print(result)  # "HELLO"
```

### Importing Modules

Modules are imported using the `import` keyword.

```risor copy
import mymod

import mymod as mod
```

By default the Risor CLI will look for modules as `.risor` files in the
current working directory.

You can also import specific attributes from a module using the `from` keyword.

```risor copy
from mymod import myfunc

from mymod import myfunc as f
```

### Strings

Simple strings are declared using double quotes, as in Go:

```risor copy
s := "hello"
```

Multiline, raw strings are also supported using backticks:

```risor copy
s := `
"one"
"two"
`
```

Templated strings are defined using single quotes, and variables are interpolated
between curly braces:

```risor copy
name := "Joe"
s := 'Hello, {name}'
```

### Data Structures

Risor supports lists, maps, and sets.

```risor copy
// Values contained in data structures can hold mixed types
mylist := [1, "two", 3.0]

// Map keys are always strings
mymap := {
    "one": 1,
    "two": 2,
    "three": 3,
}

othermap := {
    foo: "bar" // keys can be unquoted if they are valid identifiers
}

myset := {1, 2, 3}
```

Membership tests are performed using the `in` operator:

```risor copy
mylist := [1, 2, 3]
print(1 in mylist)  // true
```

### Comments

Single-line comments are defined using `//` or `#`, and multiline comments are
defined using `/*` and `*/`.

```risor copy
// This is a single-line comment

# This is also a single-line comment

/* 
This is a multiline comment
*/
```

### Channels

Risor supports Go-style channels for concurrent communication:

```risor copy
// Create a buffered channel with capacity 1
c := chan(1)

// Send a value to the channel
c <- "hello"

// Receive a value from the channel
x := <-c

// Close a channel
close(c)
```

Risor channels behave like Go channels in many ways, however they support sending
and receiving any Risor object type. Also when ranging over a channel, in Risor
you receive both the index and value of the current item.

```risor copy
func work(count) {
    mychan := chan(5)
    go func() {
        for i := 0; i < count; i++ {
            mychan <- rand.float()
        }
        close(mychan)
    }()
    return mychan
}

// Different from Go: ranging over a channel yields both the index and value
for i, value := range work(5) {
    print(i, value)
}
```

### Goroutines

Risor supports launching goroutines using the `go` keyword:

```risor copy
// Launch a goroutine
go func() {
    // Do some work
}()

// Use a channel for communication
c := chan(1)
go func() {
    c <- 42
}()
x := <-c
```

### Spawn

The `spawn` function spawns a new goroutine and returns a `thread` object. The
thread object can be used to wait for the goroutine to finish and retrieve its
return value.

```risor copy
// Spawn a function and wait for its result
result := spawn(func(x) { return x * 2 }, 21).wait()
print(result)  // 42

// Spawn multiple functions
threads := []
for i := 0; i < 5; i++ {
    threads.append(spawn(func(x) { return x ** 2 }, i))
}
results := threads.map(func(t) { t.wait() })
print(results)  // [0, 1, 4, 9, 16]
```

### Defer

The `defer` statement allows you to schedule a function call to be run after the
current function completes:

```risor copy
func example() {
    defer print("This will be printed last")
    print("This will be printed first")
}

example()
```

### Try-Catch Error Handling

Risor provides a `try` function for error handling:

```risor copy
result := try(
    func() {
        // Code that might raise an error
        error("Something went wrong")
    },
    func(err) {
        // Error handler
        print("Caught error:", err)
        return "fallback value"
    }
)
```

See the [try](builtins#try) built-in for more information.


---
context/docs/modules/_meta.json
---
{
  "aws": {
    "title": "aws"
  },
  "base64": {
    "title": "base64"
  },
  "bcrypt": {
    "title": "bcrypt"
  },
  "bytes": {
    "title": "bytes"
  },
  "carbon": {
    "title": "carbon"
  },
  "cli": {
    "title": "cli"
  },
  "color": {
    "title": "color"
  },
  "errors": {
    "title": "errors"
  },
  "exec": {
    "title": "exec"
  },
  "filepath": {
    "title": "filepath"
  },
  "fmt": {
    "title": "fmt"
  },
  "gha": {
    "title": "gha"
  },
  "http": {
    "title": "http"
  },
  "image": {
    "title": "image"
  },
  "isatty": {
    "title": "isatty"
  },
  "jmespath": {
    "title": "jmespath"
  },
  "json": {
    "title": "json"
  },
  "kubernetes": {
    "title": "kubernetes"
  },
  "math": {
    "title": "math"
  },
  "net": {
    "title": "net"
  },
  "os": {
    "title": "os"
  },
  "pgx": {
    "title": "pgx"
  },
  "rand": {
    "title": "rand"
  },
  "regexp": {
    "title": "regexp"
  },
  "sched": {
    "title": "sched"
  },
  "semver": {
    "title": "semver"
  },
  "sql": {
    "title": "sql"
  },
  "strconv": {
    "title": "strconv"
  },
  "strings": {
    "title": "strings"
  },
  "tablewriter": {
    "title": "tablewriter"
  },
  "template": {
    "title": "template"
  },
  "time": {
    "title": "time"
  },
  "uuid": {
    "title": "uuid"
  },
  "vault": {
    "title": "vault"
  },
  "yaml": {
    "title": "yaml"
  }
}

---
context/docs/modules/aws.mdx
---
import { Callout } from 'nextra/components';

# aws

<Callout type="info" emoji="ℹ️">
  This module requires that Risor has been compiled with the `aws` Go build tag.
  When compiling **manually**, [make sure you specify `-tags aws`](https://github.com/risor-io/risor#build-and-install-the-cli-from-source).
</Callout>

The `aws` module exposes a simple interface that wraps the AWS SDK v2 for Go.
Create a client by providing the name of the service you want to use. All API
calls for that service are then made available on the client.

Speciying a config is optional, but can be used to configure the client.

## Functions

### client

```go filename="Function signature"
client(service string, config map | aws.config) aws.client
```

Creates a new AWS client for the given service. The `config` parameter is
optional and can be used to configure the client. All service API calls are
made available on the client.

```go copy filename="Example"
>>> aws.client("s3")
aws.client(service=s3, region=us-east-1)
>>> aws.client("ec2")
aws.client(service=ec2, region=us-east-1)
>>> aws.client("ec2", {region: "us-west-2"})
aws.client(service=ec2, region=us-west-2)
```

### config

```go filename="Function signature"
config(config map) aws.config
```

Creates a new AWS config with the given configuration map.

```go copy filename="Example"
>>> aws.config({region: "us-east-2"})
aws.config(region=us-east-2)
```

Available configuration options:

```json
{
  "region": "us-east-1",
  "credentials": {
    "key": "AKID",
    "secret": "SECRET",
    "session": "SESSION_TOKEN"
  },
  "profile": "custom_profile",
  "credentials_files": ["test/credentials"],
  "config_files": ["test/config"]
}
```

## S3 Client Usage

```go copy
>>> s3 := aws.client("s3")
>>> s3.list_buckets()["Buckets"]
[{"CreationDate "2023-07-26T01:16:19Z", "Name "example-12345"}]
>>> s3.create_bucket({Bucket: 'test-{rand.int()}'})
{"Location": "/test-2769212968479898940", "ResultMetadata": {}}
```

## Services

Support for these services is built into the Risor CLI:

- `apigatewayv2`
- `athena`
- `backup`
- `cloudformation`
- `cloudfront`
- `cloudtrail`
- `cloudwatch`
- `cloudwatchlogs`
- `ddb`
- `ebs`
- `ec2`
- `ecr`
- `ecs`
- `eks`
- `elasticache`
- `elasticsearchse`
- `eventbridge`
- `firehose`
- `glue`
- `iam`
- `kinesis`
- `kms`
- `lambda`
- `ram`
- `rds`
- `redshift`
- `route53`
- `s3`
- `secretsmanager`
- `sesv2`
- `sfn`
- `sns`
- `sqs`
- `sts`
- `wafv2`
- `xray`


---
context/docs/modules/base64.mdx
---
# base64

## Functions

### decode

```go filename="Function signature"
decode(s string, pad bool) byte_slice
```

Decode base64 string s to a byte_slice, with padding if pad is true.
If not provided, pad defaults to false.

```go copy filename="Example"
>>> base64.decode("aGVsbG8=")
byte_slice("hello")
```

### encode

```go filename="Function signature"
encode(b byte_slice, pad bool) string
```

Encode byte_slice b to a base64 string. The encoded string is padded
if pad is true. If not provided, pad defaults to false.

```go copy filename="Example"
>>> base64.encode("hello")
"aGVsbG8="
```

### url_decode

```go filename="Function signature"
url_decode(s string, pad bool) byte_slice
```

Decode base64 string s to a byte slice using the alternate base64 codec.
The string is understood to be padded if pad is true. If not provided, pad
defaults to false.

```go copy filename="Example"
>>> base64.url_decode("YWJjK2Zvbz9iYXI9YmF6")
byte_slice("abc+foo?bar=baz")
```

### url_encode

```go filename="Function signature"
url_encode(b byte_slice, pad bool) string
```

Encode byte slice b to a base64 string using the alternate base64 codec.
The encoded string is padded if pad is true. If not provided, pad defaults
to false. The encoded string is safe for use in URLs and file names.

```go
>>> base64.url_encode("abc+foo?bar=baz")
"YWJjK2Zvbz9iYXI9YmF6"
```


---
context/docs/modules/bcrypt.mdx
---
# bcrypt

The `bcrypt` module provides functions to hash and verify passwords using the
bcrypt algorithm.

The core functionality is provided by
[golang.org/x/crypto/bcrypt](https://pkg.go.dev/golang.org/x/crypto/bcrypt).

## Functions

### hash

```go filename="Function signature"
hash(password string, cost int = bcrypt.default_cost) byte_slice
```

Hash the password using bcrypt with the given cost. The cost is the number of
rounds to use. The cost must be between bcrypt.min_cost and bcrypt.max_cost. If
not provided, the cost defaults to bcrypt.default_cost (10).

```go copy filename="Example"
>>> bcrypt.hash("password")
byte_slice("$2a$10$vGwQDlEmqYug7JP.w/acKOProf3HsIYO3wI9CUxuxOc/RpqwWD0/C")
```

Note that the bcrypt hash is non-deterministic due to the random salt used in
the hashing process.

### compare

```go filename="Function signature"
compare(hash byte_slice, password string) bool
```

Compare the password with the bcrypt hash. Raises an error if the password does
not match the hash.

```go copy filename="Example"
>>> bcrypt.compare("$2a$10$vGwQDlEmqYug7JP.w/acKOProf3HsIYO3wI9CUxuxOc/RpqwWD0/C", "password")
>>> bcrypt.compare("$2a$10$vGwQDlEmqYug7JP.w/acKOProf3HsIYO3wI9CUxuxOc/RpqwWD0/C", "oops")
crypto/bcrypt: hashedPassword is not the hash of the given password
```

## Constants

### min_cost

```go filename="Constant"
min_cost int
```

The minimum cost that can be used for hashing.

```go copy filename="Example"
>>> bcrypt.min_cost
4
```

### max_cost

```go filename="Constant"
max_cost int
```

The maximum cost that can be used for hashing.

```go copy filename="Example"
>>> bcrypt.max_cost
31
```

### default_cost

```go copy filename="Example"
default_cost int
```

The default cost that is used for hashing if not provided.

```go copy filename="Example"
>>> bcrypt.default_cost
10
```


---
context/docs/modules/bytes.mdx
---
# bytes

## Functions

### clone

```go filename="Function signature"
clone(b byte_slice) byte_slice
```

Clone returns a new byte slice containing the same bytes as the given byte slice.

```go copy filename="Example"
>>> bytes.clone(byte_slice([1, 2, 3, 4]))
byte_slice("\x01\x02\x03\x04")
```

### contains_any

```go filename="Function signature"
contains_any(b byte_slice, chars string) bool
```

Reports whether any of the UTF-8-encoded code points in the string
are present in the byte_slice.

```go copy filename="Example"
>>> bytes.contains_any(byte_slice("Hello"), "abco")
true
>>> bytes.contains_any(byte_slice("Hello"), "abc")
false
```

### contains_rune

```go filename="Function signature"
contains_rune(b byte_slice, r rune) bool
```

Reports whether the rune is contained in the UTF-8-encoded byte slice.

```go copy filename="Example"
>>> bytes.contains_rune(byte_slice("Hello"), "H")
true
>>> bytes.contains_rune(byte_slice("Hello"), "h")
false
```

### contains

```go filename="Function signature"
contains(b, subslice byte_slice) bool
```

Contains reports whether subslice is within b.

```go copy filename="Example"
>>> bytes.contains(byte_slice("seafood"), byte_slice("foo"))
true
>>> bytes.contains(byte_slice("seafood"), byte_slice("bar"))
false
```

### count

```go filename="Function signature"
count(s, sep byte_slice) int
```

Counts the number of non-overlapping instances of sep in s. If sep is an empty
slice, Count returns 1 + the number of UTF-8-encoded code points in s.

```go copy filename="Example"
>>> bytes.count(byte_slice("cheese"), byte_slice("e"))
3
```

### equals

```go filename="Function signature"
equals(a, b byte_slice) bool
```

Reports whether a and b are the same length and contain the same bytes.

```go copy filename="Example"
>>> bytes.equals(byte_slice("Hello"), byte_slice("Hello"))
true
>>> bytes.equals(byte_slice("Hello"), byte_slice("hello"))
false
```

### has_prefix

```go filename="Function signature"
has_prefix(s byte_slice, prefix byte_slice) bool
```

Tests whether the byte slice s begins with prefix.

```go copy filename="Example"
>>> bytes.has_prefix(byte_slice("Gopher"), byte_slice("Go"))
true
>>> bytes.has_prefix(byte_slice("Gopher"), byte_slice("C"))
false
```

### has_suffix

```go filename="Function signature"
has_suffix(s byte_slice, suffix byte_slice) bool
```

Tests whether the byte slice s ends with suffix.

```go copy filename="Example"
>>> bytes.has_suffix(byte_slice("Amigo"), byte_slice("go"))
true
>>> bytes.has_suffix(byte_slice("Amigo"), byte_slice("O"))
false
```

### index_any

```go filename="Function signature"
index_any(s byte_slice, chars string) int
```

Interprets s as a sequence of UTF-8-encoded code points. Returns the byte
index of the first occurrence in s of any of the code points in chars. Returns
-1 if chars is empty or if there are no code point in common.

```go copy filename="Example"
>>> bytes.index_any(byte_slice("chicken"), "aeiou")
2
>>> bytes.index_any(byte_slice("bcd"), "aeiou")
-1
```

### index_byte

```go filename="Function signature"
index_byte(b byte_slice, c byte) int
```

Returns the index of the first occurrence of c in b, or -1 if c is not present.

```go copy filename="Example"
>>> bytes.index_byte(byte_slice("golang"), "g")
0
>>> bytes.index_byte(byte_slice("golang"), "x")
-1
```

### index_rune

```go filename="Function signature"
index_rune(s byte_slice, r rune) int
```

Interprets s as a sequence of UTF-8-encoded code points. Returns the byte index
of the first occurrence in s of the given rune. Returns -1 if rune is not present.

```go copy filename="Example"
>>> bytes.index_rune(byte_slice("chicken"), "k")
4
>>> bytes.index_rune(byte_slice("chicken"), "d")
-1
```

### index

```go filename="Function signature"
index(s, sep byte_slice) int
```

Returns the index of the first occurrence of sep in s, or -1 if sep is not present.

```go copy filename="Example"
>>> bytes.index(byte_slice("chicken"), byte_slice("ken"))
4
>>> bytes.index(byte_slice("chicken"), byte_slice("kex"))
-1
```

### repeat

```go filename="Function signature"
repeat(b byte_slice, count int) byte_slice
```

Returns a new byte slice consisting of count copies of b.

```go copy filename="Example"
>>> bytes.repeat(byte_slice("a"), 3)
byte_slice("aaa")
```

### replace_all

```go filename="Function signature"
replace_all(s, old, new byte_slice) byte_slice
```

Returns a copy of the slice s with all non-overlapping instances of old
replaced by new.

```go copy filename="Example"
>>> bytes.replace_all(byte_slice("aaa"), byte_slice("a"), byte_slice("b"))
byte_slice("bbb")
```

### replace

```go filename="Function signature"
replace(s, old, new byte_slice, n int) byte_slice
```

Returns a copy of the slice s with the first n non-overlapping instances of old
replaced by new.

```go copy filename="Example"
>>> bytes.replace(byte_slice("aaa"), byte_slice("a"), byte_slice("b"), 2)
byte_slice("bba")
```


---
context/docs/modules/carbon.mdx
---
# carbon

The `carbon` module provides a convenient set of utilities for working with
dates and times. These functions are meant to aid writing more readable and
maintainable date/time code.

The core functionality is provided by
[github.com/golang-module/carbon](https://github.com/golang-module/carbon).

## Module

```go copy filename="Function signature"
carbon(input ...object)
```

The `carbon` module object itself is callable in order to provide a shorthand for
initializing a new carbon object.

Three input variations are supported:

- No input: Returns the current time as a carbon object.
- A string input: Parses the string into a carbon object.
- A time input: Converts the time into a carbon object.

```go copy filename="Example"
>>> carbon()
carbon.carbon(2024-02-03 12:03:55)
>>> carbon("2015-03-01 12:01:00")
carbon.carbon(2015-03-01 12:01:00)
>>> carbon(time.now())
carbon.carbon(2024-02-03 12:03:55)
```

## Functions

### now

```go filename="Function signature"
now(timezone ...string) carbon
```

Returns the current time as a carbon object. A timezone string may optionally
be provided.

```go filename="Example"
>>> carbon.now()
carbon.carbon(2024-02-03 12:03:55)
>>> carbon.now("America/Sao_Paulo").timezone()
"-03"
```

### parse

```go filename="Function signature"
parse(value, timezone ...string) carbon
```

Parses the time string into a carbon object. A timezone may optionally be provided.
If the time string is invalid, an error is raised.

```go filename="Example"
>>> carbon.parse("2021-03-20")
carbon.carbon(2021-03-20 00:00:00)
>>> carbon.parse("2024-02-03 12:03:55")
carbon.carbon(2024-02-03 12:03:55)
>>> carbon.parse("2024-02-03 12:03:55", "America/Sao_Paulo")
carbon.carbon(2024-02-03 12:03:55)
>>> carbon.parse("oops")
// value error: invalid time string (got "oops")
```

### yesterday

```go filename="Function signature"
yesterday(timezone ...string) carbon
```

Returns a time object for yesterday, at the current time of day. A timezone
may optionally be provided.

```go filename="Example"
>>> carbon.yesterday()
carbon.carbon(2024-02-02 12:03:55)
```

### tomorrow

```go filename="Function signature"
tomorrow(timezone ...string) carbon
```

Returns a time object for tomorrow, at the current time of day. A timezone
may optionally be provided.

```go filename="Example"
>>> carbon.tomorrow()
carbon.carbon(2024-02-04 12:03:55)
```

## Types

### carbon

The carbon object represents a point in time and offers a variety of helper
methods for performing date and time operations. Many of the operations reflect
ways humans think about dates and times, such as "add a day" or "get the age".

#### Methods

##### add_day

```go filename="Method signature"
add_day() carbon
```

Returns a new carbon object with the day incremented by one.

```go filename="Example"
>>> c := carbon.now()
>>> c.add_day()
carbon.carbon(2024-02-04 12:03:55)
```

##### add_days

```go filename="Method signature"
add_days(days int) carbon
```

Returns a new carbon object with the day incremented by the specified number of days.

```go filename="Example"
>>> c := carbon.now()
>>> c.add_days(7)
carbon.carbon(2024-02-10 12:03:55)
```

##### sub_day

```go filename="Method signature"
sub_day() carbon
```

Returns a new carbon object with the day decremented by one.

```go filename="Example"
>>> c := carbon.now()
>>> c.sub_day()
carbon.carbon(2024-02-02 12:03:55)
```

##### sub_days

```go filename="Method signature"
sub_days(days int) carbon
```

Returns a new carbon object with the day decremented by the specified number of days.

```go filename="Example"
>>> c := carbon.now()
>>> c.sub_days(7)
carbon.carbon(2024-01-27 12:03:55)
```

##### timezone

```go filename="Method signature"
timezone(tz string) carbon
```

Returns a new carbon object with the timezone set to the specified timezone string.

```go filename="Example"
>>> c := carbon.now()
>>> c.timezone("America/New_York")
carbon.carbon(2024-02-03 07:03:55)
```

##### age

```go filename="Method signature"
age(other carbon) int
```

Returns the age (in years) between the current carbon object and the specified carbon object.

```go filename="Example"
>>> c1 := carbon.parse("2000-01-01")
>>> c2 := carbon.now()
>>> c2.age(c1)
24
```

##### days_in_month

```go filename="Method signature"
days_in_month() int
```

Returns the number of days in the month of the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15")
>>> c.days_in_month()
29
```

##### days_in_year

```go filename="Method signature"
days_in_year() int
```

Returns the number of days in the year of the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15")
>>> c.days_in_year()
366
```

##### week_of_month

```go filename="Method signature"
week_of_month() int
```

Returns the week of the month for the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15")
>>> c.week_of_month()
3
```

##### week_of_year

```go filename="Method signature"
week_of_year() int
```

Returns the week of the year for the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15")
>>> c.week_of_year()
7
```

##### timestamp

```go filename="Method signature"
timestamp() int64
```

Returns the Unix timestamp (in seconds) for the current carbon object.

```go filename="Example"
>>> c := carbon.now()
>>> c.timestamp()
1677886635
```

##### string

```go filename="Method signature"
string() string
```

Returns the string representation of the current carbon object in the format
"YYYY-MM-DD HH:MM:SS".

```go filename="Example"
>>> c := carbon.now()
>>> c.string()
"2024-02-03 12:03:55"
```

##### is_valid

```go filename="Method signature"
is_valid() bool
```

Returns true if the current carbon object represents a valid date and time,
false otherwise.

```go filename="Example"
>>> c1 := carbon.parse("2024-02-29")
>>> c1.is_valid()
false
>>> c2 := carbon.parse("2024-02-28")
>>> c2.is_valid()
true
```

##### is_am

```go filename="Method signature"
is_am() bool
```

Returns true if the current carbon object represents a time in the AM
(before noon), false otherwise.

```go filename="Example"
>>> c1 := carbon.parse("2024-02-03 08:00:00")
>>> c1.is_am()
true
>>> c2 := carbon.parse("2024-02-03 15:00:00")
>>> c2.is_am()
false
```

##### is_pm

```go filename="Method signature"
is_pm() bool
```

Returns true if the current carbon object represents a time in the PM (after noon), false otherwise.

```go filename="Example"
>>> c1 := carbon.parse("2024-02-03 08:00:00")
>>> c1.is_pm()
false
>>> c2 := carbon.parse("2024-02-03 15:00:00")
>>> c2.is_pm()
true
```

##### is_leap_year

```go filename="Method signature"
is_leap_year() bool
```

Returns true if the year of the current carbon object is a leap year, false otherwise.

```go filename="Example"
>>> c1 := carbon.parse("2024-02-29")
>>> c1.is_leap_year()
true
>>> c2 := carbon.parse("2023-02-28")
>>> c2.is_leap_year()
false
```

##### is_future

```go filename="Method signature"
is_future() bool
```

Returns true if the current carbon object represents a time in the future
(after the current time), false otherwise.

```go filename="Example"
>>> c1 := carbon.parse("2024-02-03 15:00:00")
>>> c1.is_future()
true
>>> c2 := carbon.now()
>>> c2.is_future()
false
```

##### is_past

```go filename="Method signature"
is_past() bool
```

Returns true if the current carbon object represents a time in the past
(before the current time), false otherwise.

```go filename="Example"
>>> c1 := carbon.parse("2024-02-03 15:00:00")
>>> c1.is_past()
false
>>> c2 := carbon.now().sub_days(1)
>>> c2.is_past()
true
```

##### is_today

```go filename="Method signature"
is_today() bool
```

Returns true if the current carbon object represents a time on the current day,
false otherwise.

```go filename="Example"
>>> c1 := carbon.now()
>>> c1.is_today()
true
>>> c2 := carbon.parse("2024-02-02 15:00:00")
>>> c2.is_today()
false
```

##### is_yesterday

```go filename="Method signature"
is_yesterday() bool
```

Returns true if the current carbon object represents a time on the previous day,
false otherwise.

```go filename="Example"
>>> c1 := carbon.now()
>>> c1.is_yesterday()
false
>>> c2 := carbon.yesterday()
>>> c2.is_yesterday()
true
```

##### day

```go filename="Method signature"
day() int
```

Returns the day of the month for the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.day()
15
```

##### month

```go filename="Method signature"
month() int
```

Returns the month for the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.month()
2
```

##### year

```go filename="Method signature"
year() int
```

Returns the year for the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.year()
2024
```

##### hour

```go filename="Method signature"
hour() int
```

Returns the hour for the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.hour()
12
```

##### minute

```go filename="Method signature"
minute() int
```

Returns the minute for the current carbon object.
```go filename="Example"
>>> c := carbon.parse("2024-02-15 12:30:00")
>>> c.minute()
30
```

##### second

```go filename="Method signature"
second() int
```

Returns the second for the current carbon object.

```go filename="Example"
>>> c := carbon.parse("2024-02-15 12:30:45")
>>> c.second()
45
```

##### diff_for_humans

```go filename="Method signature"
diff_for_humans(other carbon) string
```

Returns a human-readable string representing the difference between the current
carbon object and the specified carbon object.

```go filename="Example"
>>> c1 := carbon.now()
>>> c2 := c1.add_days(7)
>>> c2.diff_for_humans(c1)
"1 week"
```

##### std_time

```go filename="Method signature"
std_time() time.Time
```

Returns a time.Time object representing the current carbon object.

```go filename="Example"
>>> c := carbon.now()
>>> t := c.std_time()
>>> fmt.Println(t)
2024-02-03 12:03:55 +0000 UTC
```

##### to_date_string

```go filename="Method signature"
to_date_string() string
```

Returns a string representation of the current carbon object in the format
"YYYY-MM-DD".

```go filename="Example"
>>> c := carbon.now()
>>> c.to_date_string()
"2024-02-03"
```

##### to_time_string

```go filename="Method signature"
to_time_string() string
```

Returns a string representation of the current carbon object in the format
"HH:MM:SS".

```go filename="Example"
>>> c := carbon.parse("2024-02-03 12:30:45")
>>> c.to_time_string()
"12:30:45"
```

##### to_datetime_string

```go filename="Method signature"
to_datetime_string() string
```

Returns a string representation of the current carbon object in the format
"YYYY-MM-DD HH:MM:SS".

```go filename="Example"
>>> c := carbon.parse("2024-02-03 12:30:45")
>>> c.to_datetime_string()
"2024-02-03 12:30:45"
```


---
context/docs/modules/cli.mdx
---
import { Callout } from 'nextra/components';

# cli

Module `cli` is used to build command line apps written in the Risor. Common
CLI features are supported, including commands, flags, arguments, usage, and
automatic help generation.

<Callout type="info" emoji="ℹ️">
  This module is included by default in the Risor CLI, but must be
  independently installed when using Risor as
  a library using `go get github.com/risor-io/risor/modules/cli`
</Callout>

Behind the scenes, this module uses the [urfave/cli](https://cli.urfave.org/) library.

## Getting Started

Create a file named `myapp.risor` with the following contents. Note that you
must include the shebang line including `--` at the top of the file to ensure
that arguments and options are _passed to the app_, rather than being used as
options by the Risor binary itself.

```risor copy filename="myapp.risor"
#!/usr/bin/env risor --

from cli import app, command as c

app({
    name: "myapp",
    description: "My app description",
    commands: [
        c({
            name: "hello",
            description: "Say hello",
            action: func(ctx) {
                print("Hello, world!")
            },
        }),
    ],
}).run()
```

Now make the file executable:

```
$ chmod +x ./myapp.risor
```

You can now run the app as follows:

```
$ ./myapp.risor hello
Hello, world!
```

## Functions

### app

```go filename="Function signature"
app(options map) app
```

Returns a new app initialized with the given options. A simple app may consist
of just a `name`, `description`, and `action` function. Call `.run()` on the
app to run it.

```risor copy filename="Example"
app := cli.app({
    name: "myapp",
    description: "My app description",
    action: func(ctx) {
        print("Hello, world!")
    },
})

app.run()
```

The `app` function supports the following options:

- `action func(ctx)`: The action to run when the app is run.
- `commands []cli.command`: A list of commands that the app supports.
- `description string`: A short description of the app.
- `flags []cli.flag`: A list of flags that the app supports.
- `help_name string` : Override for the name of the app in help output.
- `name string`: The name of the app.
- `usage_text string`: The usage text for the app.
- `usage string`: The usage string for the app.
- `version string`: The version of the app.

### command

```go filename="Function signature"
command(options map) command
```

Returns a new command initialized with the given options. Commands are provided
to an app via the app's `commands` option.

```go copy filename="Example"
command := cli.command({
    name: "add",
    description: "Add numbers provided as arguments",
    action: func(ctx) {
        sum := 0
        for _, arg := range ctx.args() {
            sum += int(arg)
        }
        print(sum)
    },
})
```

The `command` function supports the following options:

- `action func(ctx)`: The function to call when the command is invoked.
- `aliases []string`: A list of aliases for the command.
- `args_usage string`: A short description of the arguments of this command.
- `args bool`: Whether this command supports arguments.
- `category string`: The category the command is part of.
- `custom_help_template string`: Text template for the command help topic.
- `description string`: A longer explanation of how the command works.
- `flags []cli.flag`: A list of flags that the command supports.
- `help_name string`: Full name of command for help, defaults to full command name, including parent commands.
- `hidden bool`: Hide this command from help or completion.
- `hide_help_command bool`: Whether to hide the command from the help command.
- `hide_help bool` Hide the built-in help command and help flag.
- `name string`: The name of the command.
- `usage_text string`: Custom text to show in USAGE section of help.
- `usage string`: A short description of the usage of this command.
- `use_short_option_handling bool`: Enables short-option handling so the user can combine several single-character bool flags into one.

### flag

```go filename="Function signature"
flag(options map) flag
```

Returns a flag that may be used with an app or command. Supported flag types
include `string`, `int`, `bool`, `float`, `string_slice`, `int_slice`,
and `float_slice`.

A default value for the flag may be provided using the `value` option. The flag
type is inferred from the `value` option if a `type` is not specified.

```go copy filename="Example string flag"
cli.flag({
    name: "food",
    aliases: ["f"],
    usage: "The type of food to eat",
    env_vars: ["FOOD"], // read from this environment variable, if present
    value: "pizza",     // default value
    type: "string",     // flag type: string, int, bool, etc.
})
```

```go copy filename="Example int flag"
cli.flag({
    name: "count",
    aliases: ["c"],
    usage: "The number of items to process",
    value: 1,
})
```

```go copy filename="Example bool flag"
cli.flag({
    name: "verbose",
    aliases: ["v"],
    usage: "Enable verbose output",
    value: false,
})
```

## Types

### app

An app represents the main entry point for a command-line program. It contains
commands, is customized with flags, and is executed via `app.run()`.

### ctx

A ctx object is passed through to each handler action in a cli app. It is
used to retrieve context-specific args and parsed command-line options.

Attributes on the ctx object include:

| Name             | Type                         | Description                                                             |
| ---------------- | ---------------------------- | ----------------------------------------------------------------------- |
| args             | func() []string              | Returns the command-line arguments                                      |
| narg             | func() int                   | Returns the number of arguments                                         |
| value            | func(name string) object     | Returns the value of the flag corresponding to `name`                   |
| count            | func(name string) int        | Returns the count of the flag corresponding to `name`                   |
| flag_names       | func() []string              | Returns the names of all flags used by this context and parent contexts |
| local_flag_names | func() []string              | Returns the names of all flags used by this context                     |
| is_set           | func(name string) bool       | Returns true if the flag corresponding to `name` is set                 |
| set              | func(name string, value obj) | Sets the value of the flag corresponding to `name`                      |
| num_flags        | func() int                   | Returns the number of flags set                                         |
| bool             | func(name string) bool       | Returns the value of the bool flag corresponding to `name`              |
| int              | func(name string) int        | Returns the value of the int flag corresponding to `name`               |
| string           | func(name string) string     | Returns the value of the string flag corresponding to `name`            |
| string_slice     | func(name string) []string   | Returns the value of the string slice flag corresponding to `name`      |

### command

A command represents a sub-command of an app. It contains its own flags and
has an associated action. Commands may have sub-commands.

### flag

A flag is used to parse command-line flags in a cli app. Flags may be specified
on a cli app directly, as well as on commands.


---
context/docs/modules/color.mdx
---
# color

The `color` module provides functions to colorize text in the
terminal.

The core functionality is provided by
[github.com/fatih/color](https://github.com/fatih/color).

Configuring colors and other text attributes is done using the various
[constants](#constants) described below. Multiple constants can be passed
to functions in this module to combine attributes.

## Module

```go copy filename="Function signature"
color(options ...int) color.color
```

The `color` module object itself is callable, which is a shorthand for
`color.color()`.

```go copy filename="Example"
>>> color(color.fg_green).printf("hello!\n")
// colorized output
```

## Functions

### color

```go filename="Function signature"
color(options ...int) color.color
```

Creates a new color object with the specified options.

```go copy filename="Example"
>>> c := color.color(color.fg_red, color.bold)
```

### set

```go filename="Function signature"
set(options ...int)
```

Sets the terminal color to the specified options.

```go copy filename="Example"
>>> color.set(color.fg_green, color.bold)
```

### unset

```go filename="Function signature"
unset()
```

Resets the terminal color to the default.

```go copy filename="Example"
>>> color.unset()
```

## Types

### color

Defines a custom color object.

#### Methods

##### sprintf

```go filename="Method signature"
sprintf(format string, a ...object) string
```

Formats the string with the color object.

```go copy filename="Example"
>>> c := color.color(color.fg_red, color.bold)
>>> c.sprintf("Hello, %s!", "world")
"\x1b[31;1mHello, world!\x1b[0;22m"
>>> print(c.sprintf("Hello, %s!", "world"))
// colorized output
```

##### fprintf

```go filename="Method signature"
fprintf(w io.writer, format string, a ...object)
```

Writes the colorized, formatted string to the given writer.

```go copy filename="Example"
>>> b := buffer()
>>> c.fprintf(b, "Hello, %s!\n", "world")
>>> b
buffer("\x1b[31;1mHello, world!\n\x1b[0m")
```

##### printf

```go filename="Method signature"
printf(format string, a ...object)
```

Writes the colorized, formatted string to the standard output. Note
you may need to include a trailing newline to flush the output.

```go copy filename="Example"
>>> c.printf("Hello, %s!\n", "world")
// colorized output
```

## Constants

| Name         | Description                             |
| ------------ | --------------------------------------- |
| reset        | Reset all attributes                    |
| bold         | Bold text                               |
| dim          | Dim text                                |
| italic       | Italic text                             |
| underline    | Underlined text                         |
| blinkslow    | Blinking text (slow)                    |
| blinkrapid   | Blinking text (rapid)                   |
| reversevideo | Reverse video                           |
| concealed    | Concealed text                          |
| crossedout   | Crossed-out text                        |
| bg_black     | Black background color                  |
| bg_blue      | Blue background color                   |
| bg_cyan      | Cyan background color                   |
| bg_green     | Green background color                  |
| bg_hiblack   | High-intensity black background color   |
| bg_hiblue    | High-intensity blue background color    |
| bg_hicyan    | High-intensity cyan background color    |
| bg_higreen   | High-intensity green background color   |
| bg_himagenta | High-intensity magenta background color |
| bg_hired     | High-intensity red background color     |
| bg_hiwhite   | High-intensity white background color   |
| bg_hiyellow  | High-intensity yellow background color  |
| bg_magenta   | Magenta background color                |
| bg_red       | Red background color                    |
| bg_white     | White background color                  |
| bg_yellow    | Yellow background color                 |
| fg_black     | Black foreground color                  |
| fg_blue      | Blue foreground color                   |
| fg_cyan      | Cyan foreground color                   |
| fg_green     | Green foreground color                  |
| fg_hiblack   | High-intensity black foreground color   |
| fg_hiblue    | High-intensity blue foreground color    |
| fg_hicyan    | High-intensity cyan foreground color    |
| fg_higreen   | High-intensity green foreground color   |
| fg_himagenta | High-intensity magenta foreground color |
| fg_hired     | High-intensity red foreground color     |
| fg_hiwhite   | High-intensity white foreground color   |
| fg_hiyellow  | High-intensity yellow foreground color  |
| fg_magenta   | Magenta foreground color                |
| fg_red       | Red foreground color                    |
| fg_white     | White foreground color                  |
| fg_yellow    | Yellow foreground color                 |


---
context/docs/modules/errors.mdx
---
# errors

Module `errors` provides functions for creating error values.

## Comparison with Go

Risor error values are similar to those in Go, in that they are values that
represent an error condition. However, error handling is different in Risor
because it has the concept of raising and catching errors.

This approach has two main benefits in Risor:

1. It keeps Risor code more concise, which is desirable for a scripting language.
2. The fact that functions in Risor always return exactly one value means that
   function results can be piped without having to check for errors.

## Functions

### new

```go filename="Function signature"
new(string) error
```

Returns a new error value with the given message.

```go filename="Example"
>>> err := errors.new("something went wrong")
>>> err
something went wrong
```


---
context/docs/modules/exec.mdx
---
# exec

The `exec` module is used to run external commands.

Like the underlying Go `os/exec` package, this module does not invoke the system
shell, expand glob patterns, or handle other shell features.

## Callable

The `exec` module itself is callable, using one of two signatures. The preferred
form is now:

```go filename="Function signature"
exec(args []string, opts map) result
```

The old form that is still supported for backwards compatibility is:

```go filename="Function signature"
exec(name string, args []string, opts map) result
```

This provides a shorthand way to build and run a command. The function returns a
`result` object containing the stdout and stderr produced by running the command.
The `opts` argument is optional.

```go copy filename="Example"
>>> exec(["echo", "TEST"]).stdout
byte_slice("TEST\n")
```

The `opts` argument may be a map containing any of the following keys:

| Name   | Type                          | Description                              |
| ------ | ----------------------------- | ---------------------------------------- |
| dir    | string                        | The working directory of the command.    |
| env    | map                           | The environment given to the command.    |
| stdin  | string, byte_slice, or reader | The standard input given to the command. |
| stdout | writer                        | The standard output destination.         |
| stderr | writer                        | The standard error destination.          |

## Functions

### command

Two signatures are supported for the `command` function. The preferred form is now:

```go filename="Function signature"
command(args []string) command
```

The old form that is still supported for backwards compatibility is:

```go filename="Function signature"
command(name string, args ...string) command
```

Creates a new command with the given name and arguments. The command can then
be executed with its `run`, `start`, `output`, or `combined_output` methods.
Before the command is run, its `path`, `dir`, and `env` attributes may be set.
Read more about the [command](#command-1) type below.

```go copy filename="Example"
>>> exec.command(["echo", "TEST"]).output()
byte_slice("TEST\n")
```

### look_path

```go filename="Function signature"
look_path(name string) string
```

Searches for the named executable in the directories contained in the PATH
environment variable. If the name contains a slash, it is tried directly,
without consulting the PATH. Otherwise, the result is the absolute path to
the named executable.

```go copy filename="Example"
>>> exec.look_path("echo")
"/bin/echo"
```

## Types

### command

Represents an external command that is being built and run.

#### Attributes

| Name            | Type              | Description                                                                   |
| --------------- | ----------------- | ----------------------------------------------------------------------------- |
| path            | string            | The path to the executable.                                                   |
| dir             | string            | The working directory of the command.                                         |
| env             | []string          | The environment given to the command.                                         |
| stdout          | byte_slice        | The standard output produced by the command.                                  |
| stderr          | byte_slice        | The standard error produced by the command.                                   |
| run             | func()            | Runs the command and waits for it to complete.                                |
| output          | func() byte_slice | Runs the command and returns its standard output.                             |
| combined_output | func() byte_slice | Runs the command and returns its combined standard output and standard error. |
| start           | func()            | Starts the command but does not wait for it to complete.                      |
| wait            | func()            | Waits for the command to exit.                                                |

#### Examples

```go copy filename="Example"
>>> c := exec.command("pwd")
>>> c.dir = "/dev"
>>> c.run()
>>> c.stdout
"/dev\n"
```

### result

Represents the result of running an external command.

#### Attributes

| Name   | Type       | Description                                  |
| ------ | ---------- | -------------------------------------------- |
| stdout | byte_slice | The standard output produced by the command. |
| stderr | byte_slice | The standard error produced by the command.  |
| pid    | int        | The process ID of the command.               |

#### Examples

```go copy filename="Example"
>>> result := exec("ls")
>>> result.stdout
"file1\nfile2\n"
```


---
context/docs/modules/filepath.mdx
---
# filepath

The `filepath` module contains utilities thare are used to manipulate file paths
with operating system-specific separators.

## Functions

### abs

```go filename="Function signature"
abs(path string) string
```

Returns the absolute representation of path. If the path is not absolute it will
be joined with the current working directory to create the corresponding absolute path.

```go copy filename="Example"
>>> filepath.abs("foo/bar")
"/home/user/foo/bar"
>>> filepath.abs("../foo/bar")
"/home/foo/bar"
```

Learn more: [filepath.Abs](https://pkg.go.dev/path/filepath#Abs).

### base

```go filename="Function signature"
base(path string) string
```

Returns the last element of path with any trailing slashes removed.
If path is empty, "." is returned.

```go copy filename="Example"
>>> filepath.base("foo/bar")
"bar"
>>> filepath.base("foo/bar/")
"bar"
>>> filepath.base("test.txt")
"test.txt"
>>> filepath.base("")
"."
```

Learn more: [filepath.Base](https://pkg.go.dev/path/filepath#Base).

### clean

```go filename="Function signature"
clean(path string) string
```

Returns the shortest path name equivalent to path by purely lexical processing.

```go copy filename="Example"
>>> filepath.clean("foo/bar/../baz")
"foo/baz"
>>> filepath.clean("foo/bar/./baz")
"foo/bar/baz"
>>> filepath.clean("foo/bar/../../baz")
"baz"
```

Learn more: [filepath.Clean](https://pkg.go.dev/path/filepath#Clean).

### dir

```go filename="Function signature"
dir(path string) string
```

Returns all but the last element of path, typically the path's directory.

```go copy filename="Example"
>>> filepath.dir("foo/bar")
"foo"
>>> filepath.dir("foo/bar/")
"foo"
>>> filepath.dir("test.txt")
"."
```

Learn more: [filepath.Dir](https://pkg.go.dev/path/filepath#Dir).

### ext

```go filename="Function signature"
ext(path string) string
```

Returns the file name extension used by path. The extension is the suffix
beginning at the final dot in the final element of path. The result it is empty
if there is no dot.

```go copy filename="Example"
>>> filepath.ext("foo/bar.txt")
".txt"
>>> filepath.ext("foo/bar")
""
>>> filepath.ext("foo/bar.tar.gz")
".gz"
```

Learn more: [filepath.Ext](https://pkg.go.dev/path/filepath#Ext).

### is_abs

```go filename="Function signature"
is_abs(path string) bool
```

Returns true if the path is absolute.

```go copy filename="Example"
>>> filepath.is_abs("/foo/bar")
true
>>> filepath.is_abs("foo/bar")
false
```

Learn more: [filepath.IsAbs](https://pkg.go.dev/path/filepath#IsAbs).

### join

```go filename="Function signature"
join(paths ...string) string
```

Returns the result of joining the given path elements with the operating
system-specific path separator.

```go copy filename="Example"
>>> filepath.join("foo", "bar")
"foo/bar"
>>> filepath.join("foo", "bar", "baz")
"foo/bar/baz"
```

Learn more: [filepath.Join](https://pkg.go.dev/path/filepath#Join).

### match

```go filename="Function signature"
match(pattern, name string) bool
```

Returns true if the file name matches the shell pattern.

```go copy filename="Example"
>>> filepath.match("*.txt", "foo.txt")
true
>>> filepath.match("*.txt", "foo.tar.gz")
false
```

Learn more: [filepath.Match](https://pkg.go.dev/path/filepath#Match).

### rel

```go filename="Function signature"
rel(basepath, targpath string) string
```

Returns a relative path that is lexically equivalent to targpath when joined
to basepath with an intervening separator.

```go copy filename="Example"
>>> filepath.rel("/home/user", "/home/user/foo/bar")
"foo/bar"
>>> filepath.rel("/home/user", "/home/user/foo/../bar")
"bar"
>>> filepath.rel("/home/user", "/home/user/foo/../../bar")
"../bar"
```

Learn more: [filepath.Rel](https://pkg.go.dev/path/filepath#Rel).

### split_list

```go filename="Function signature"
split_list(path string) []string
```

Splits path immediately following the final separator, separating it into a
directory and file name component. If there is no separator in path, split_list
returns an empty dir and file set to path.

```go copy filename="Example"
>>> filepath.split_list("/home/user/foo/bar")
["/home/user/foo", "bar"]
>>> filepath.split_list("/home/user/foo")
["/home/user", "foo"]
>>> filepath.split_list("foo")
["", "foo"]
```

Learn more: [filepath.Split](https://pkg.go.dev/path/filepath#Split).

### split

```go filename="Function signature"
split(path string) []string
```

Splits the path immediately following the final separator, returning a list of two items: the directory and the file name. If there is no separator in the path, an empty directory and the file name are returned.

```go copy filename="Example"
>>> filepath.split("/home/user/foo/bar")
["/home/user/foo", "bar"]
>>> filepath.split("/home/user/foo")
["/home/user", "foo"]
>>> filepath.split("test.txt")
["", "test.txt"]
```

Learn more: [filepath.Split](https://pkg.go.dev/path/filepath#Split).

### walk_dir

```go filename="Function signature"
walk_dir(root string, fn func(path string))
```

Walks the file tree at root, calling fn for each file or directory in the tree,
including root. Files are walked in lexical order. Symbolic links are not
followed.

```go copy filename="Example"
>>> filepath.walk_dir("/home/user/foo", func(path, dir_entry, err) { print(path) })
"/home/user/foo"
"/home/user/foo/bar"
"/home/user/foo/test.txt"
```

Learn more: [filepath.WalkDir](https://pkg.go.dev/path/filepath#WalkDir).


---
context/docs/modules/fmt.mdx
---
import { Callout } from 'nextra/components'

# fmt

The `fmt` module provides functions for formatting and printing strings.

Usually you should use Risor's top-level `print` and `printf` functions instead
of using `fmt.print` and `fmt.printf` since they are equivalent.


## Functions

### errorf

```go filename="Function signature"
errorf(string, ...any) error
```

Returns a new error with the given message formatted according to the format.

```go filename="Example"
>>> err := fmt.errorf("something went wrong: %d", 42)
>>> err
something went wrong: 42
```

### printf

```go filename="Function signature"
printf(string, ...any)
```

Prints the formatted string to the standard output.

```go filename="Example"
>>> fmt.printf("Hello, %s!\n", "world")
Hello, world!
```

### print

```go filename="Function signature"
print(...any)
```

Prints the given values to the standard output. Note that in Risor the output
may not be printed to the terminal until a newline character is printed.

```go filename="Example"
>>> fmt.print("Hello, ", "world", "!\n")
Hello, world!
```


---
context/docs/modules/gha.mdx
---
# gha

Module `gha` provides utility functions when working inside GitHub Actions.

## Functions

### is_debug

```go filename="Function signature"
is_debug() bool
```

Gets whether Actions Step Debug is on or not
(by checking the `RUNNER_DEBUG` environment variable)

```go copy filename="Example"
>>> gha.is_debug()
false
```

### log_debug

```go filename="Function signature"
log_debug(msg string) bool
```

Writes debug message to log. This message is only shown when Action Step Debug
is on. See also: [`gha.is_debug()`](#is_debug)

```go copy filename="Example"
>>> gha.log_debug("Hello world")
::debug::Hello world
```

### log_notice

```go filename="Function signature"
log_notice(msg string, props={})
```

Adds a notice issue.

The [`props` parameter](#annotation-properties) can specify thing like a file
path and line number to add the issue to.

```go copy filename="Example"
>>> gha.log_notice("Hello world")
::notice::Hello world
>>> gha.log_notice("Hello world", {title: "Risor", file: "somefile.txt", line: 5})
::notice file=somefile.txt,title=Risor,line=5::Hello world
```

### log_warning

```go filename="Function signature"
log_warning(msg string, props={})
```

Adds a warning issue.

The [`props` parameter](#annotation-properties) can specify thing like a file
path and line number to add the issue to.

```go copy filename="Example"
>>> gha.log_warning("Hello world")
::warning::Hello world
>>> gha.log_warning("Hello world", {title: "Risor", file: "somefile.txt", line: 5})
::warning file=somefile.txt,title=Risor,line=5::Hello world
```

### log_error

```go filename="Function signature"
log_error(msg string, props={})
```

Adds a error issue.

The [`props` parameter](#annotation-properties) can specify thing like a file
path and line number to add the issue to.

```go copy filename="Example"
>>> gha.log_error("Hello world")
::error::Hello world
>>> gha.log_error("Hello world", {title: "Risor", file: "somefile.txt", line: 5})
::error file=somefile.txt,title=Risor,line=5::Hello world
```

### start_group

```go filename="Function signature"
start_group(name string)
```

Begins an output group. Output until the next `end_group` will be foldable
in this group.

```go copy filename="Example"
>>> gha.start_group("My group")
::group::My group
```

### end_group

```go filename="Function signature"
end_group()
```

End an output group.

```go copy filename="Example"
>>> gha.end_group()
::endgroup::
```

### set_output

```go filename="Function signature"
set_output(name string, value any)
```

Sets a GitHub Action output variable.

This function makes use of the `GITHUB_OUTPUT` environment variable, if set.
Otherwise it falls back to the ([deprecated](https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/))
workflow command of `::set-output::`.

```go copy filename="Example"
>>> gha.set_output("my-var", "some value")
::set-output name=my-var::some value
```

### set_env

```go filename="Function signature"
set_env(name string, value any)
```

Sets a GitHub Action environment variable for this action and future actions
in the same job.

This function makes use of the `GITHUB_ENV` environment variable, if set.
Otherwise it falls back to the ([deprecated](https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/))
workflow command of `::set-env::`.

```go copy filename="Example"
>>> gha.set_output("MY_VAR", "some value")
::set-env name=MY_VAR::some value
>>> os.getenv("MY_VAR")
"some value"
```

### add_path

```go filename="Function signature"
add_path(dir string)
```

Prepends directory to the PATH (for this action and future actions)

This function makes use of the `GITHUB_PATH` environment variable, if set.
Otherwise it falls back to the ([deprecated](https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/))
workflow command of `::add-path::`.

```go copy filename="Example"
>>> gha.add_path("/some/new/dir")
::add-path::/some/new/dir
>>> os.getenv("PATH")
"/some/new/dir:/usr/local/bin:/usr/bin"
```

## Types

### Annotation properties

The following keys can be supplied when creating an issue with the
[`log_notice`](#log_notice), [`log_warning`](#log_warning),
or [`log_error`](#log_error) functions.
All keys are optional.

| Key        | Type   | Description                                                                                                                                        |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| title      | string | A title for the annotation.                                                                                                                        |
| file       | string | The path of the file for which the annotation should be created (relative to the repository root directory)                                        |
| line       | int    | The start line for the annotation.                                                                                                                 |
| column     | int    | The start column for the annotation. Cannot be sent when `line` and `end_line` are different values.                                               |
| end_line   | int    | The end line for the annotation. Defaults to `line` when `line` is provided.                                                                       |
| end_column | int    | The end column for the annotation. Cannot be sent when `line` and `end_line` are different values. Defaults to `column` when `column` is provided. |


---
context/docs/modules/http.mdx
---
import { Callout, Steps } from 'nextra/components';

# http

The `http` module provides functions for making HTTP requests and defines
[request](#request-1) and [response](#response) types.

<Callout type="info" emoji="ℹ️">
    Using the [fetch](/docs/builtins#fetch) built-in function instead of this
    module is encouraged. This module provides more low-level control of how
    HTTP requests are built and sent, which may be useful in some situations.
</Callout>

The approach used to make an HTTP request is as follows:

<Steps>
### Create a Request

```go copy
req := http.get("https://api.ipify.org")
```

### Send the Request

```go copy
res := req.send()
```

### Handle the Response

```go copy
print("response status:", res.status, "text:", res.text())
```

</Steps>

## Functions

### get

```go filename="Function signature"
get(url string, headers map, params map) request
```

Creates a new GET request with the given URL, headers, and query parameters. The
headers and query parameters are optional. The request that is returned can then
be executed using its `send` method. Read more about the [request](#request)
type below.

```go copy filename="Example"
>>> http.get("https://api.ipify.org").send()
http.response(status: "200 OK", content_length: 14)
```

### delete

```go filename="Function signature"
delete(url string, headers map, params map) request
```

Creates a new DELETE request with the given URL, headers, and query parameters.
The headers and query parameters are optional.

### head

```go filename="Function signature"
head(url string, headers map, params map) request
```

Creates a new HEAD request with the given URL, headers, and query parameters.
The headers and query parameters are optional.

### listen_and_serve

```go filename="Function signature"
listen_and_serve(addr string, handler func(w response_writer, r request))
```

Starts an HTTP server that listens on the specified address and calls the
handler function to handle requests. As a convenience, the handler function
may return a map or list object to be marshaled as JSON, or a string or byte
slice object which will be written as the response body as-is.

### listen_and_serve_tls

```go filename="Function signature"
listen_and_serve_tls(addr, cert_file, key_file string, handler func(w response_writer, r request))
```

Acts the same as `listen_and_serve`, but uses the provided certificate and key
files to work over HTTPS.

### patch

```go filename="Function signature"
patch(url string, headers map, body byte_slice) request
```

Creates a new PATCH request with the given URL, headers, and request body.
The headers and request body parameters are optional.

### post

```go filename="Function signature"
post(url string, headers map, body byte_slice) request
```

Creates a new POST request with the given URL, headers, and request body.
The headers and request body parameters are optional.

### put

```go filename="Function signature"
put(url string, headers map, body byte_slice) request
```

Creates a new PUT request with the given URL, headers, and request body.
The headers and request body parameters are optional.

### request

```go filename="Function signature"
request(url string, options map) request
```

Creates a new request with the given URL and options. If provided, the options
map may contain any of the following keys:

| Name    | Type                 | Description                                            |
| ------- | -------------------- | ------------------------------------------------------ |
| method  | string               | The HTTP method to use.                                |
| headers | map                  | The headers to send with the request.                  |
| params  | map                  | The query parameters to send with the request.         |
| body    | byte_slice or reader | The request body.                                      |
| timeout | int                  | Request timeout in milliseconds.                       |
| data    | object               | Object to marshal as JSON and send in the request body |

If both `body` and `data` are provided, the `body` value will be used.

## Types

### request

Represents an HTTP request that is being built and sent.

#### Attributes

| Name           | Type                           | Description                                  |
| -------------- | ------------------------------ | -------------------------------------------- |
| url            | string                         | The URL of the request.                      |
| content_length | int                            | The length of the request body.              |
| header         | map                            | The headers of the request.                  |
| send           | func()                         | Sends the request.                           |
| add_header     | func(key string, value object) | Adds a header to the request.                |
| add_cookie     | func(key string, value map)    | Adds a cookie to the request.                |
| set_body       | func(body byte_slice)          | Sets the request body.                       |
| set_data       | func(data object)              | Request body as an object to marshal to JSON |

### response

Represents an HTTP response.

#### Attributes

| Name           | Type          | Description                      |
| -------------- | ------------- | -------------------------------- |
| status         | string        | The status of the response.      |
| status_code    | int           | The status code of the response. |
| proto          | string        | The protocol of the response.    |
| content_length | int           | The length of the response body. |
| header         | map           | The headers of the response.     |
| cookies        | map           | The cookies of the response.     |
| response       | object        | The response body.               |
| json           | func() object | The response body as JSON.       |
| text           | func() string | The response body as text.       |
| close          | func()        | Closes the response body.        |

### response_writer

Represents an HTTP response writer.

#### Attributes

| Name         | Type                    | Description                                                  |
| ------------ | ----------------------- | ------------------------------------------------------------ |
| add_header   | func(key, value string) | Adds a header to the header map that will be sent.           |
| del_header   | func(key string)        | Deletes a header from the header map that will be sent.      |
| write        | func(object)            | Writes the object as the HTTP reply.                         |
| write_header | func(status_code int)   | Sends an HTTP response header with the provided status code. |


---
context/docs/modules/image.mdx
---
# image

Module `image` provides 2-D image encoding and decoding. Image pixels are
represented as RGBA values.

Supported image formats: `bmp`, `jpg`, `png`.

## Functions

### decode

```go filename="Function signature"
decode(b byte_slice) image
```

Returns an image object that is decoded from the given bytes. If a byte_buffer
or io.Reader is given, it is automatically converted to a byte_slice.

```go copy filename="Example"
>>> img := image.decode(open("/path/to/test.png"))
>>> img.width
3440
>>> img.height
1416
>>> img.dimensions()
{"height": 1416, "width": 3440}
>>> img.bounds()
{"max": {"x": 3440, "y": 1416}, "min": {"x": 0, "y": 0}}
>>> img.at(0, 0)
color(r=52428 g=31611 b=7967 a=65535)
```

### encode

```go filename="Function signature"
encode(img image, format string) byte_slice
```

Encodes the given image object into the given format, returning the encoded bytes.

```go copy filename="Example"
>>> img
image(width=256, height=256)
>>> image.encode(img, "png")
byte_slice(...)
```

## Types

### image

The `image` type represents a 2-D image as a rectangular grid of color values.

#### Attributes

| Name       | Type           | Description                                 |
| ---------- | -------------- | ------------------------------------------- |
| width      | int            | The width of the image in pixels            |
| height     | int            | The height of the image in pixels           |
| dimensions | func() map     | The width and height of the image in pixels |
| bounds     | func() map     | The bounds of the image                     |
| at         | func(x, y int) | Returns the color at the given coordinates  |

### color

The `color` type represents a color as an RGBA value.

#### Attributes

| Name | Type | Description                 |
| ---- | ---- | --------------------------- |
| rgba | list | The RGBA value of the color |


---
context/docs/modules/isatty.mdx
---
# isatty

The `isatty` module provides functions to check if the current process is
connected to a terminal.

The core functionality is provided by
[github.com/mattn/go-isatty](https://github.com/mattn/go-isatty).

## Module

```go copy filename="Function signature"
isatty() bool
```

The `isatty` module object itself is callable, and returns a boolean indicating
whether the process is connected to a terminal. This module-level function does
not differentiate between cygwin and non-cygwin terminals, returning true in
both cases.

```go copy filename="Example"
>>> isatty()
true
```

## Functions

### is_terminal

```go filename="Function signature"
is_terminal() bool
```

Returns true if the current process is connected to a terminal.

```go copy filename="Example"
>>> isatty.is_terminal()
true
```

### is_cygwin_terminal

```go filename="Function signature"
is_cygwin_terminal() bool
```

Returns true if the current process is connected to a Cygwin terminal.

```go copy filename="Example"
>>> isatty.is_cygwin_terminal()
false
```


---
context/docs/modules/jmespath.mdx
---
# jmespath

Module `jmespath` provides json filtering and manipulation using the Jmespath expression syntax.

## Functions

### jmespath

```go filename="Function signature"
jmespath(in object, expression string)
```

Returns the filtered object after the expression has been applied.

```go filename="Example"
>>> data := {
  "locations": [
    {"name": "Seattle", "state": "WA"},
    {"name": "New York", "state": "NY"},
    {"name": "Bellevue", "state": "WA"},
    {"name": "Olympia", "state": "WA"},
  ],
} | jmespath("locations[?state == 'WA'].name | sort(@) | {WashingtonCities: join(', ', @)}")
{
    "WashingtonCities": "Bellevue, Olympia, Seattle"
}

>>> print(jmespath(data, "split(WashingtonCities, ',')")[0])
"Bellevue"
```


---
context/docs/modules/json.mdx
---
# json

Module `json` provides JSON encoding and decoding.

## Functions

### marshal

```go filename="Function signature"
marshal(v object) string
```

Returns a JSON string representing the given value. Raises an error if the value
cannot be marshalled.

```go copy filename="Example"
>>> m := {one: 1, two: 2}
>>> json.marshal(m)
"{\"one\":1,\"two\":2}"
```

### unmarshal

```go filename="Function signature"
unmarshal(s string) object
```

Returns the value represented by the given JSON string. Raises an error if the
string cannot be unmarshalled.

```go copy filename="Example"
>>> json.unmarshal("{\"one\":1,\"two\":2}")
{"one": 1, "two": 2}
>>> json.unmarshal("{bad") // raises value error
```

### valid

```go filename="Function signature"
valid(s string) bool
```

Returns whether the given string is valid JSON.

```go copy filename="Example"
>>> json.valid("42")
true
>>> json.valid("{oops")
false
```


---
context/docs/modules/kubernetes.mdx
---
import { Callout } from 'nextra/components';

# kubernetes

<Callout type="info" emoji="ℹ️">
  This module requires that Risor has been compiled with the `k8s` Go build tag.
  When compiling **manually**, [make sure you specify `-tags k8s`](https://github.com/risor-io/risor#build-and-install-the-cli-from-source).
</Callout>

Module `k8s` provides methods for getting, listing, deleting and updating resources using the Kubernetes API.

## Functions

### get

```go filename="Function signature"
get(kind string, options object) object
```

Can be used to get a single object or a list of objects from the Kubernetes API.

```go filename="Example"
# get all namespaces
k8s.get("namespace.v1")

# get a specific namespace
k8s.get("namespace.v1", {"name": "default"})

# get pods by labels
k8s.get("pod.v1", {"namespace": "kube-system", "selector": "k8s-app=kube-apiserver" })

# get a specific pod by name
k8s.get("pod.v1", {"namespace": "kube-system", "name": "kube-apiserver-i-036c4abb51cd79a10"})

# get pods not running
k8s.get("pod.v1", {"fieldSelector": "status.phase!=Running"})
```

### delete

```go filename="Function signature"
delete(kind string, options object) object
```

Can be used to delete a single object or a list of objects from the Kubernetes API.

```go filename="Example"
# delete pods not running
k8s.delete("pod.v1", {"fieldSelector": "status.phase!=Running"})
```

### apply

```go filename="Function signature"
apply(manifest string, options object)
```

Can be used to apply (create or update) a kubernetes object from a JSON or YAML manifest

```go filename="Example"
manifest := string(os.read_file("/tmp/foo.yaml"))
apply(manifest, {"namespace": "my-namespace"})
```


---
context/docs/modules/math.mdx
---
# math

Module `math` provides constants and mathematical functions. It is primarily
a wrapper of the Go [math](https://pkg.go.dev/math) package, however it also
includes a `sum` function for summing a list of numbers.

Risor provides equivalence between float and int types, so many of the
functions in this module accept both float and int as inputs. In the documentation below, "number" is used to refer to either float or int.

## Constants

### PI

```go filename="Constant"
PI float
```

```go copy filename="Example"
>>> math.PI
3.141592653589793
```

### E

```go filename="Constant"
E float
```

```go copy filename="Example"
>>> math.E
2.718281828459045
```

## Functions

### abs

```go filename="Function signature"
abs(x number) number
```

Returns the absolute value of x.

```go copy filename="Example"
>>> math.abs(-2)
2
>>> math.abs(3.3)
3.3
```

### sqrt

```go filename="Function signature"
sqrt(x number) float
```

Returns the square root of x.

```go copy filename="Example"
>>> math.sqrt(4)
2
>>> math.sqrt(2)
1.4142135623730951
```

### min

```go filename="Function signature"
min(x, y number) float
```

Returns the smaller of x or y.

```go copy filename="Example"
>>> math.min(1, 2)
1.0
>>> math.min(3, -2.5)
-2.5
```

### max

```go filename="Function signature"
max(x, y number) float
```

Returns the larger of x or y.

```go copy filename="Example"
>>> math.max(1, 2)
2.0
>>> math.max(-3, 2.5)
2.5
```

### floor

```go filename="Function signature"
floor(x number) number
```

Returns the largest integer value less than or equal to x.

```go copy filename="Example"
>>> math.floor(2.5)
2
>>> math.floor(-2.5)
-3
>>> math.floor(3)
3
```

### ceil

```go filename="Function signature"
ceil(x number) number
```

Returns the smallest integer value greater than or equal to x.

```go copy filename="Example"
>>> math.ceil(2.5)
3
>>> math.ceil(-2.5)
-2
```

### sin

```go filename="Function signature"
sin(x number) float
```

Returns the sine of x.

```go copy filename="Example"
>>> math.sin(0)
0
>>> math.sin(math.PI / 2)
1
```

### cos

```go filename="Function signature"
cos(x number) float
```

Returns the cosine of x.

```go copy filename="Example"
>>> math.cos(0)
1
>>> math.cos(math.PI / 2)
0
```

### tan

```go filename="Function signature"
tan(x number) float
```

Returns the tangent of x.

```go copy filename="Example"
>>> math.tan(0)
0
>>> math.tan(math.PI / 4)
0.9999999999999998
```

### mod

```go filename="Function signature"
mod(x, y number) float
```

Returns the remainder of x divided by y.

```go copy filename="Example"
>>> math.mod(5, 2)
1
>>> math.mod(5, 3)
2
```

### log

```go filename="Function signature"
log(x number) float
```

Returns the natural logarithm of x.

```go copy filename="Example"
>>> math.log(1)
0
>>> math.log(math.E)
1
```

### log10

```go filename="Function signature"
log10(x number) float
```

Returns the base 10 logarithm of x.

```go copy filename="Example"
>>> math.log10(1)
0
>>> math.log10(10)
1
```

### log2

```go filename="Function signature"
log2(x number) float
```

Returns the base 2 logarithm of x.

```go copy filename="Example"
>>> math.log2(1)
0
>>> math.log2(8)
3
```

### pow

```go filename="Function signature"
pow(x, y number) float
```

Returns x raised to the power of y.

```go copy filename="Example"
>>> math.pow(2, 3)
8
>>> math.pow(2, 0.5)
1.4142135623730951
```

### pow10

```go filename="Function signature"
pow10(x number) float
```

Returns 10 raised to the power of x.

```go copy filename="Example"
>>> math.pow10(0)
1
>>> math.pow10(1)
10
>>> math.pow10(2)
100
```

### is_inf

```go filename="Function signature"
is_inf(x number) bool
```

Returns true if x is positive or negative infinity.

```go copy filename="Example"
>>> math.is_inf(math.inf)
true
>>> math.is_inf(-math.inf)
true
>>> math.is_inf(0)
false
```

### round

```go filename="Function signature"
round(x number) float
```

Returns x rounded to the nearest integer.

```go copy filename="Example"
>>> math.round(1.4)
1
>>> math.round(1.5)
2
```

### sum

```go filename="Function signature"
sum(list) float
```

Returns the sum of all numbers in a list.

```go copy filename="Example"
>>> math.sum([1, 2, 3])
6
>>> math.sum([])
0
```


---
context/docs/modules/net.mdx
---
# net

The `net` module provides a set of functions for working with network addresses
and performing network lookups.

This module does not yet provide a way to create network connections or servers.
Feel free to open a GitHub issue if you would like to see this functionality
added.

The core functionality is provided by the Go standard library's
[`net`](https://pkg.go.dev/net) package.

## Functions

### interface_addrs

```go filename="Function signature"
interface_addrs() []string
```

Returns a list of the system's network interfaces.

```go filename="Example"
>>> net.interface_addrs()
["127.0.0.1/8", "::1/128", "fe80::1/64", "etc."]
```

### join_host_port

```go filename="Function signature"
join_host_port(host, port string) string
```

Joins the host and port together.

```go filename="Example"
>>> net.join_host_port("localhost", "8080")
"localhost:8080"
```

### lookup_addr

```go filename="Function signature"
lookup_addr(addr string) (string, error)
```

Looks up the host name of the specified address.

```go filename="Example"
>>> net.lookup_addr("127.0.0.1")
["localhost"]
```

### lookup_host

```go filename="Function signature"
lookup_host(host string) []string
```

Looks up the IP addresses of the specified host.

```go filename="Example"
>>> net.lookup_host("google.com")
["172.253.62.113", "172.253.62.102", "172.253.62.139", "etc."]
```

### lookup_ip

```go filename="Function signature"
lookup_ip(host string) []net.ip
```

Looks up the IP addresses of the specified host.

```go filename="Example"
>>> net.lookup_ip("google.com")
[net.ip(172.253.62.113),
 net.ip(172.253.62.102),
 net.ip(172.253.62.139),
 etc.]
```


---
context/docs/modules/os.mdx
---
# os

Module `os` provides a platform-independent interface to operating system
functionality.

By default, this module interacts with the host operating system normally by
calling the underlying Go `os` package. However, alternative OS abstraction
layers may be used via the Go [WithOS](https://pkg.go.dev/github.com/risor-io/risor@v1.2.0/os#WithOS) function. This assists with sandboxing scripts and providing
access to object storage like AWS S3 via a filesystem-like interface.

## Attributes

### stdin

`stdin` is an open file pointing to the standard input for the process.

```go copy filename="Example"
>>> os.stdin.read()
byte_slice("hello world")
```

### stdout

`stdout` is an open file pointing to the standard output for the process.

```go copy filename="Example"
>>> os.stdout.write("hello world")
11
```

## Functions

### chdir

```go filename="Function signature"
chdir(dir string)
```

Changes the working directory to dir.

```go copy filename="Example"
>>> os.chdir("/tmp")
>>> os.getwd()
"/tmp"
```

### create

```go filename="Function signature"
create(name string) File
```

Creates or truncates the named file.

```go copy filename="Example"
>>> f := os.create("foo.txt")
>>> f.write("hello world")
11
>>> f.close()
```

### environ

```go filename="Function signature"
environ() list
```

Returns a copy of strings representing the environment, in the form "key=value".

```go copy filename="Example"
>>> os.environ()
["TERM=xterm-256color", "SHELL=/bin/bash", "USER=alice", ...]
```

### exit

```go filename="Function signature"
exit(code int)
```

Terminates the program with the given exit code.

```go copy filename="Example"
>>> os.exit(0)
```

### getenv

```go filename="Function signature"
getenv(key string) string
```

Returns the value of the environment variable key.

```go copy filename="Example"
>>> os.getenv("USER")
"alice"
```

### getpid

```go filename="Function signature"
getpid() int
```

Returns the current process ID.

```go copy filename="Example"
>>> os.getpid()
1234
```

### getuid

```go filename="Function signature"
getuid() int
```

Returns the current user ID.

```go copy filename="Example"
>>> os.getuid()
501
```

### getwd

```go filename="Function signature"
getwd() string
```

Returns the current working directory.

```go copy filename="Example"
>>> os.getwd()
"/home/alice"
```

### hostname

```go filename="Function signature"
hostname() string
```

Returns the host name reported by the kernel.

```go copy filename="Example"
>>> os.hostname()
"alice-macbook-pro-1.local"
```

### mkdir_all

```go filename="Function signature"
mkdir_all(path string, perm int)
```

Creates a directory named path, along with any necessary parent directories.

```go copy filename="Example"
>>> os.mkdir_all("/tmp/foo/bar", 0755)
```

### mkdir_temp

```go filename="Function signature"
mkdir_temp(dir, prefix string) string
```

Creates a new temporary directory in the directory dir, using prefix to generate
its name.

```go copy filename="Example"
>>> os.mkdir_temp("/tmp", "foo")
"/tmp/foo4103914411"
```

### mkdir

```go filename="Function signature"
mkdir(path string, perm int)
```

Creates a new directory with the specified name and permission bits. If
a permissions value is not specified, 0755 is used.

```go copy filename="Example"
>>> os.mkdir("/tmp/foo", 0755)
```

### open

```go filename="Function signature"
open(name string) File
```

Opens the named file.

```go copy filename="Example"
>>> f := os.open("foo.txt")
>>> f.read()
byte_slice("hello world")
>>> f.close()
```

### read_dir

```go filename="Function signature"
read_dir(name string) list
```

Returns a list of directory entries sorted by filename. If a name is not
specified, the current directory is used.

```go copy filename="Example"
>>> os.read_dir("/tmp")
[dir_entry(name=foo.txt, type=regular), dir_entry(name=bar.txt, type=regular)]
```

### read_file

```go filename="Function signature"
read_file(name string) byte_slice
```

Reads the named file and returns its contents.

```go copy filename="Example"
>>> os.read_file("/tmp/foo.txt")
byte_slice("hello world")
```

### remove

```go filename="Function signature"
remove(name string)
```

Removes the named file or empty directory.

```go copy filename="Example"
>>> os.remove("/tmp/old/junk.txt")
```

### remove_all

```go filename="Function signature"
remove_all(name string)
```

Removes path and any children it contains.

```go copy filename="Example"
>>> os.remove_all("/tmp/junk")
```

### rename

```go filename="Function signature"
rename(old, new string)
```

Renames (moves) old to new.

```go copy filename="Example"
>>> os.rename("old.txt", "new.txt")
```

### setenv

```go filename="Function signature"
setenv(key, value string)
```

Sets the value of the environment variable key to value.

```go copy filename="Example"
>>> os.setenv("USER", "bob")
>>> os.getenv("USER")
"bob"
```

### stat

```go filename="Function signature"
stat(name string) FileInfo
```

Returns a FileInfo describing the named file.

```go copy filename="Example"
>>> os.stat("example.txt")
file_info(name=example.txt, mode=-rw-r--r--, size=84, mod_time=2023-08-06T08:45:56-04:00)
```

### symlink

```go filename="Function signature"
symlink(old, new string)
```

Creates a symbolic link new pointing to old.

```go copy filename="Example"
>>> os.symlink("foo.txt", "bar.txt")
```

### temp_dir

```go filename="Function signature"
temp_dir() string
```

Returns the default directory to use for temporary files.

```go copy filename="Example"
>>> os.temp_dir()
"/tmp"
```

### unsetenv

```go filename="Function signature"
unsetenv(key string)
```

Unsets the environment variable key.

```go copy filename="Example"
>>> os.unsetenv("USER")
>>> os.getenv("USER")
""
```

### user_cache_dir

```go filename="Function signature"
user_cache_dir() string
```

Returns the default root directory to use for user-specific non-essential data.

```go copy filename="Example"
>>> os.user_cache_dir()
"/home/alice/.cache"
```

### user_config_dir

```go filename="Function signature"
user_config_dir() string
```

Returns the default root directory to use for user-specific configuration data.

```go copy filename="Example"
>>> os.user_config_dir()
"/home/alice/.config"
```

### user_home_dir

```go filename="Function signature"
user_home_dir() string
```

Returns the current user's home directory.

```go copy filename="Example"
>>> os.user_home_dir()
"/home/alice"
```

### write_file

```go filename="Function signature"
write_file(name string, data byte_slice / string)
```

Writes the given byte_slice or string to the named file.

```go copy filename="Example"
>>> os.write_file("example.txt", "hey!")
>>> os.read_file("example.txt")
byte_slice("hey!")
```


---
context/docs/modules/pgx.mdx
---
# pgx

Module `pgx` is used to connect to and query PostgreSQL databases.

The core functionality is provided by the
[pgx](https://github.com/jackc/pgx) library.

## Functions

### connect

```go filename="Function signature"
connect(dsn string) conn
```

Connect to the database specified by the dsn string.

```go copy filename="Example"
>>> conn := pgx.connect("postgres://user:pass@localhost:5432/db")
>>> conn.query("SELECT * FROM users")
[{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
>>> conn.close()
```

## Types

### conn

The `conn` object is a connection to a PostgreSQL database.

#### Methods

##### exec

```go filename="Method signature"
exec(sql string, args ...object) string
```

Execute sql by supplying the name of a prepared statement or a SQL string.
Arguments may be referenced positionally in the SQL string as $1, $2, etc.

```go copy filename="Example"
>>> conn.exec("INSERT INTO users (name) VALUES ($1)", "Alice")
```

##### query

```go filename="Method signature"
query(sql string, args ...object) list
```

Runs a query on the server and reads returns a list of records generated by the
query.

```go copy filename="Example"
>>> conn.query("SELECT * FROM users")
[{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
```

##### close

```go filename="Method signature"
close()
```

Close the connection.

```go copy filename="Example"
>>> conn.close()
```


---
context/docs/modules/rand.mdx
---
# rand

Module `rand` provides pseudo-random number generation.

As with the Go [math/rand](https://pkg.go.dev/math/rand) package
on which it is based, this module is not safe for use for
security-sensitive applications.

## Functions

### float

```go filename="Function signature"
float() float
```

Returns a random float between 0 and 1.

```go filename="Example"
>>> rand.float()
0.44997274093073925
```

### int

```go filename="Function signature"
int() int
```

Returns a non-negative pseudo-random 64 bit integer.

```go filename="Example"
>>> rand.int()
1667297659146365586
```

### intn

```go filename="Function signature"
intn(n int) int
```

Returns a non-negative pseudo-random 64 bit integer in the range [0, n).

```go filename="Example"
>>> rand.intn(10)
7
```

### norm_float

```go filename="Function signature"
norm_float() float
```

Returns a normally distributed float in the range [-math.MaxFloat64, +math.MaxFloat64]
with standard normal distribution (mean = 0, stddev = 1).

```go filename="Example"
>>> rand.norm_float()
0.44997274093073925
```

### exp_float

```go filename="Function signature"
exp_float() float
```

Returns an exponentially distributed float in the range (0, +math.MaxFloat64]
with an exponential distribution whose rate parameter (lambda) is 1 and whose
mean is 1/lambda (1).

```go filename="Example"
>>> rand.exp_float()
0.17764313580968902
```

### shuffle

```go filename="Function signature"
shuffle(list)
```

Shuffles a list in place and returns it.

```go filename="Example"
>>> l := [1, 2, 3, 4, 5]
>>> rand.shuffle(l)
[3, 1, 5, 4, 2]
```


---
context/docs/modules/regexp.mdx
---
# regexp

Module regexp provides regular expression matching.

The supported regular expression syntax is exactly as described
in the [Go regexp](https://pkg.go.dev/regexp) documentation.

## Functions

### compile

```go filename="Function signature"
compile(expr string) regexp
```

Compiles a regular expression string into a regexp object.

```go filename="Example"
>>> regexp.compile("a+")
regexp("a+")
>>> r := regexp.compile("a+"); r.match("a")
true
>>> r := regexp.compile("[0-9]+"); r.match("nope")
false
```

### match

```go filename="Function signature"
match(expr, s string) bool
```

Returns true if the string s contains any match of the regular expression pattern.

```go filename="Example"
>>> regexp.match("ab+a", "abba")
true
>>> regexp.match("[0-9]+", "nope")
false
```

## Types

### regexp

Represents a compiled regular expression.

#### Methods

##### regexp.match

```go filename="Method signature"
match(s string) bool
```

Returns true if the string s contains any match of the regular expression pattern.

```go filename="Example"
>>> r := regexp.compile("a+"); r.match("a")
true
```

##### regexp.find

```go filename="Method signature"
find(s string) string
```

Returns the leftmost match of the regular expression pattern in the string s.

```go filename="Example"
>>> r := regexp.compile("a+"); r.find("baaab")
"aaa"
```

##### regexp.find_all

```go filename="Method signature"
find_all(s string) []string
```

Returns a slice of all matches of the regular expression pattern in the string s.

```go filename="Example"
>>> r := regexp.compile("(du)+"); r.find_all("dunk dug in the deep end")
["du", "du"]
```

##### regexp.find_submatch

```go filename="Method signature"
find_submatch(s string) []string
```

Returns a slice of all matches of the regular expression pattern in the string s,
and the matches, if any, of its subexpressions.

```go filename="Example"
>>> r := regexp.compile("a(b+)a"); r.find_submatch("abba")
["abba", "bb"]
```

##### regexp.replace_all

```go filename="Method signature"
replace_all(s, repl string) string
```

Returns a copy of the string s with all matches of the regular expression pattern
replaced by repl.

```go filename="Example"
>>> r := regexp.compile("a+"); r.replace_all("baaab", "x")
"bxb"
```

##### regexp.split

```go filename="Method signature"
split(s string) []string
```

Splits the string s into a slice of substrings separated by the regular expression
pattern.

```go filename="Example"
>>> r := regexp.compile("a+"); r.split("baaab")
["b", "b"]
```


---
context/docs/modules/semver.mdx
---
import { Callout } from 'nextra/components';

# semver

<Callout type="info" emoji="ℹ️">
  This module requires that Risor has been compiled with the `semver` Go build tag.
  When compiling **manually**, [make sure you specify `-tags semver`](https://github.com/risor-io/risor#build-and-install-the-cli-from-source).
</Callout>

## Functions

### compare

```go filename="Function signature"
compare(v1 int, v2 int) int
```

Compares v1 and v2. Returns -1 if v1 is less than v2, 0 if both are equal, 1 if v1 is greater than v2.

```go copy filename="Example"
>>> import semver
>>> semver.compare("1.2.3", "1.2.4")
-1
```

### major

```go filename="Function signature"
major(version string) int
```

Returns the major version of the given version string.

```go copy filename="Example"
>>> import semver
>>> semver.major("1.2.3")
1
```

### minor

```go filename="Function signature"
minor(version string) int
```

Returns the minor version of the given version string.

```go copy filename="Example"
>>> import semver
>>> semver.minor("1.2.3")
2
```

### patch

```go filename="Function signature"
patch(version string) int
```

Returns the patch version of the given version string.

```go copy filename="Example"
>>> import semver
>>> semver.patch("1.2.3")
3
```

### build

```go filename="Function signature"
build(version string) string
```

Returns the build version of the given version string.

```go copy filename="Example"
>>> import semver
>>> semver.build("1.2.3+build")
"build"
```

### pre

```go filename="Function signature"
pre(version string) string
```

Pre returns the pre-release version of the given version string.

```go copy filename="Example"
>>> import semver
>>> semver.pre("1.2.3-pre")
"pre"
```

### validate

```go filename="Function signature"
validate(version string) bool
```

Returns an error if the version isn't valid.

```go copy filename="Example"
>>> import semver
>>> semver.validate("1.2.3invalid")
Invalid character(s) found in patch number "3invalid"
```

### parse

```go filename="Function signature"
parse(version string) map
```

Parses the given version string and returns a map with the major, minor, patch, pre-release, and build versions.

```go copy filename="Example"
>>> import semver
>>> semver.parse("1.2.3-pre+build")
{
  "major": 1,
  "minor": 2,
  "patch": 3,
  "pre": "pre",
  "build": "build"
}
```

### equals

```go filename="Function signature"
equals(v1 string, v2 string) bool
```

Returns whether v1 and v2 are equal.

```go copy filename="Example"
>>> import semver
>>> semver.equals("1.2.3", "1.2.3")
true
```


---
context/docs/modules/sql.mdx
---
# sql



---
context/docs/modules/strconv.mdx
---
# strconv

String conversion functions from the Go standard library.

## Functions

### atoi

```go filename="Function signature"
atoi(s string) int
```

Converts the string s to an int.

```go copy filename="Example"
>>> strconv.atoi("123")
123
>>> strconv.atoi("nope")
strconv.Atoi: parsing "nope": invalid syntax
```

### parse_bool

```go filename="Function signature"
parse_bool(s string) bool
```

Converts the string s to a bool.

```go copy filename="Example"
>>> strconv.parse_bool("true")
true
>>> strconv.parse_bool("false")
false
>>> strconv.parse_bool("nope")
strconv.ParseBool: parsing "nope": invalid syntax
```

### parse_float

```go filename="Function signature"
parse_float(s string) float
```

Converts the string s to a float.

```go copy filename="Example"
>>> strconv.parse_float("3.14")
3.14
>>> strconv.parse_float("nope")
strconv.ParseFloat: parsing "nope": invalid syntax
```

### parse_int

```go filename="Function signature"
parse_int(s string, base int = 10, bit_size int = 64) int
```

Converts the string s to an int. 

```go copy filename="Example"
>>> strconv.parse_int("123")
123
>>> strconv.parse_int("nope")
strconv.ParseInt: parsing "nope": invalid syntax
>>> strconv.parse_int("ff", 16)
255
```


---
context/docs/modules/strings.mdx
---
import { Callout } from 'nextra/components';

# strings

String manipulation functions from the Go standard library.

<Callout type="info" emoji="ℹ️">
    Note that, unlike in Go, many of these functions are also available as
    methods on string objects. See the related documentation [here](/docs/types/string). That said, using these functions **is** handy within pipe expressions.
</Callout>

## Functions

### compare

```go filename="Function signature"
compare(s1, s2 string) int
```

Compares two strings lexicographically. Returns -1 if s1 < s2, 0 if s1 == s2, and 1 if s1 > s2.

```go copy filename="Example"
>>> strings.compare("abc", "abc")
0
>>> strings.compare("abc", "abd")
-1
```

### contains

```go filename="Function signature"
contains(s, substr string) bool
```

Returns true if the string s contains substr.

```go copy filename="Example"
>>> strings.contains("abc", "b")
true
>>> strings.contains("abc", "d")
false
>>> "abc" | strings.contains("b")
true
```

### count

```go filename="Function signature"
count(s, substr string) int
```

Returns the number of non-overlapping instances of substr in s.

```go copy filename="Example"
>>> strings.count("abc", "b")
1
>>> strings.count("ababab", "ab")
3
```

### fields

```go filename="Function signature"
fields(s string) []string
```

Splits the string s around each instance of one or more consecutive white space
characters, returning a slice of substrings or any empty slice if s contains only
white space.

```go copy filename="Example"
>>> strings.fields("a b c")
["a", "b", "c"]
>>> strings.fields("")
[]
```

### has_prefix

```go filename="Function signature"
has_prefix(s, prefix string) bool
```

Returns true if the string s begins with prefix.

```go copy filename="Example"
>>> strings.has_prefix("abc", "a")
true
```

### has_suffix

```go filename="Function signature"
has_suffix(s, suffix string) bool
```

Returns true if the string s ends with suffix.

```go copy filename="Example"
>>> strings.has_suffix("abc", "c")
true
```

### index

```go filename="Function signature"
index(s, substr string) int
```

Returns the index of the first instance of substr in s, or -1 if substr is not
present in s.

```go copy filename="Example"
>>> strings.index("abc", "b")
1
>>> strings.index("abc", "d")
-1
```

### join

```go filename="Function signature"
join(a []string, sep string) string
```

Concatenates the elements of a to create a single string. The separator string
sep is placed between elements in the resulting string.

```go copy filename="Example"
>>> strings.join(["a", "b", "c"], ", ")
"a, b, c"
```

### last_index

```go filename="Function signature"
last_index(s, substr string) int
```

Returns the index of the last instance of substr in s, or -1 if substr is not
present in s.

```go copy filename="Example"
>>> strings.last_index("abc", "b")
1
>>> strings.last_index("abc", "d")
-1
```

### repeat

```go filename="Function signature"
repeat(s string, count int) string
```

Repeat returns a new string consisting of `count` copies of the string `s`.

```go copy filename="Example"
>>> strings.repeat("na", 5) + " batman"
"nanananana batman"
```

### replace_all

```go filename="Function signature"
replace_all(s, old, new string) string
```

Returns a copy of the string s with all non-overlapping instances of old
replaced by new.

```go copy filename="Example"
>>> strings.replace_all("oink oink oink", "oink", "moo")
"moo moo moo"
```

### split

```go filename="Function signature"
split(s, sep string) []string
```

Splits the string s around each instance of sep, returning a slice of
substrings or any empty slice if s does not contain sep.

```go copy filename="Example"
>>> strings.split("a,b,c", ",")
["a", "b", "c"]
```

### to_lower

```go filename="Function signature"
to_lower(s string) string
```

Returns a copy of the string s with all Unicode letters mapped to their lower
case.

```go copy filename="Example"
>>> strings.to_lower("HELLO")
"hello"
```

### to_upper

```go filename="Function signature"
to_upper(s string) string
```

Returns a copy of the string s with all Unicode letters mapped to their upper
case.

```go copy filename="Example"
>>> strings.to_upper("hello")
"HELLO"
```

### trim_prefix

```go filename="Function signature"
trim_prefix(s, prefix string) string
```

Returns s without the provided leading prefix string. If s doesn't start with
prefix, s is returned unchanged.

```go copy filename="Example"
>>> strings.trim_prefix("foo", "f")
"oo"
>>> strings.trim_prefix("foo", "b")
"foo"
```

### trim_space

```go filename="Function signature"
trim_space(s string) string
```

Returns a slice of the string s, with all leading and trailing white space
removed, as defined by Unicode.

```go copy filename="Example"
>>> strings.trim_space("  hello  ")
"hello"
```

### trim_suffix

```go filename="Function signature"
trim_suffix(s, suffix string) string
```

Returns s without the provided trailing suffix string. If s doesn't end with
suffix, s is returned unchanged.

```go copy filename="Example"
>>> strings.trim_suffix("foo", "o")
"f"
```

### trim

```go filename="Function signature"
trim(s, cutset string) string
```

Returns a slice of the string s, with all leading and trailing Unicode code
points contained in cutset removed.

```go copy filename="Example"
>>> strings.trim("¡¡¡Hello, Gophers!!!", "!¡")
"Hello, Gophers"
```


---
context/docs/modules/tablewriter.mdx
---
# tablewriter

The `tablewriter` module is used to print rows of data in a
tabular format.

The core functionality is provided by
[github.com/olekukonko/tablewriter](github.com/olekukonko/tablewriter).

There are two ways to use the `tablewriter` module:

- Use the `writer` function to create a tablewriter object and
    use its methods to configure and render the table.
- Call the tablewriter module directly to pass in rows of data and
    render the table in one action.

## Module

```go copy filename="Function signature"
tablewriter(rows [][]string, options map, writer io.writer = os.stdout)
```

Renders a table with the given rows of data. The options map can be used to set
properties of the table, such as the header, footer, and alignment. If a writer
is not provided, it defaults to stdout.

```go copy filename="Example"
>>> tablewriter([["Name", "Age"], ["Alice", 25], ["Bob", 30]])
+-------+-----+
| Name  | Age |
| Alice |  25 |
| Bob   |  30 |
+-------+-----+
```

```go copy filename="Example"
>>> tablewriter([["Alice", 25], ["Bob", 30]], {header: ["Name", "Age"], border: false, row_separator: "="})
  NAME  | AGE  
========+======
  Alice |  25  
  Bob   |  30
```

Available options:

| Option              | Type     | Description                                              |
| ------------------- | -------- | -------------------------------------------------------- |
| header              | []string | The header names for the table.                          |
| footer              | []string | The footer of the table.                                 |
| center_separator    | string   | The center separator character used to separate columns. |
| border              | bool     | Whether to draw a border around the table.               |
| auto_wrap_text      | bool     | Whether to automatically wrap text in the cells.         |
| auto_format_headers | bool     | Whether to automatically format the headers.             |
| header_alignment    | int      | The alignment of the header text.                        |
| header_line         | bool     | Whether to draw a line under the header.                 |
| alignment           | int      | The alignment of the text in the cells.                  |
| row_separator       | string   | The separator character used to separate rows.           |

## Functions

### writer

```go filename="Function signature"
tablewriter.writer(writer io.writer = os.stdout) tablewriter.writer
```

Returns a new tablewriter.writer object that writes to the given output writer.
If an output writer is not provided, it defaults to stdout.

```go copy filename="Example"
>>> w := tablewriter.writer()
>>> w.append_bulk([["Name", "Age"], ["Alice", 25], ["Bob", 30]])
>>> w.render()
+-------+-----+
| Name  | Age |
| Alice |  25 |
| Bob   |  30 |
+-------+-----+
```

## Types

### writer

A table writer object.

#### Methods

##### set_header

```go filename="Method signature"
set_header(header []string)
```

Sets the header text for columns in the table.

##### set_footer

```go filename="Method signature"
set_footer(footer []string)
```

Sets the footer text for columns in the table.

##### set_center_separator

```go filename="Method signature"
set_center_separator(separator string)
```

Sets the character used to separate columns.

##### set_border

```go filename="Method signature"
set_border(border bool)
```

Sets whether to draw a border around the table.

##### append

```go filename="Method signature"
append(row []string)
```

Appends a row to the table.

##### append_bulk

```go filename="Method signature"

append_bulk(rows [][]string)
```

Appends multiple rows to the table.

##### set_auto_wrap_text

```go filename="Method signature"
set_auto_wrap_text(auto_wrap bool)
```

Sets whether to automatically wrap text in the cells.

##### set_auto_format_headers

```go filename="Method signature"
set_auto_format_headers(auto_format bool)
```

Sets whether to automatically format the headers.

##### set_header_alignment

```go filename="Method signature"
set_header_alignment(align int)
```

Sets the alignment of the header text. See the constants section below for
acceptable values.

##### set_header_line

```go filename="Method signature"
set_header_line(header_line bool)
```

Sets whether to draw a line under the header.

##### set_alignment

```go filename="Method signature"
set_alignment(align int)
```

Sets the alignment of the text in the cells. See the constants section below for
acceptable values.

##### set_row_separator

```go filename="Method signature"
set_row_separator(separator string)
```

Sets the character used to separate rows.

##### render

```go filename="Method signature"
render()
```

Renders the table to the writer.

## Constants

### align_default

Specifies the default alignment for the text.

```go filename="Constant"
>>> tablewriter.align_default
0
```

### align_center

Specifies that text should be centered in the cell.

```go filename="Constant"
>>> tablewriter.align_center
1
```

### align_right

Specifies that text should be right-aligned in the cell.

```go filename="Constant"
>>> tablewriter.align_right
2
```

### align_left

Specifies that text should be left-aligned in the cell.

```go filename="Constant"
>>> tablewriter.align_left
3
```


---
context/docs/modules/template.mdx
---
# template

String templating functionality.

## Builtins

### render

```go filename="Function signature"
render(data object, template string) string
```

Returns the rendered template as a string.
It includes all the sprig lib functions.
You can access environment variables from the template under .Env and the passed values will be available under .Values in the template

If compiled with [`-tags k8s`](https://github.com/risor-io/risor#build-and-install-the-cli-from-source),
it also includes a k8sLookup function to get values from k8s objects.

```go filename="Example"
>>> fetch("http://ipinfo.io").json() | render("You are in {{ .Values.city }}, region {{ .Values.region }} in {{ .Values.timezone }}")
"You are in Dublin, region Leinster in Europe/Dublin"
```

## Functions

### new

```go filename="Function signature"
new(name string) template
```

Instanciates a new template object with the given name.

```go filename="Example"
tpl :=  template.new("test")
tpl.delims("{%", "%}")
```

### add

```go filename="Function signature"
add(name string, template string)
```

Adds a named template to the template object

```go filename="Example"
tpl.add("ipinfo", "You are in {% .city %}, region {% .region %} in {% .timezone %}")
```

### execute_template

```go filename="Function signature"
execute_template(data object, name string) string
```

Renders the given named template into a string.

```go filename="Example"
>>> tpl.execute_template(fetch("http://ipinfo.io").json(), "ipinfo")
"You are in Dublin, region Leinster in Europe/Dublin"
```

### parse

```go filename="Function signature"
parse(template string)
```

Parses a template into the template object

```go filename="Example"
tpl.parse("You are in {% .city %}, region {% .region %} in {% .timezone %}")
```

### execute

```go filename="Function signature"
execute(data object) string
```

Renders the templates into a string.

```go filename="Example"
>>> tpl.execute(fetch("http://ipinfo.io").json())
"You are in Dublin, region Leinster in Europe/Dublin"
```


---
context/docs/modules/time.mdx
---
# time

Module `time` provides functionality for measuring and displaying time.

This is primarily a wrapper of the Go [time](https://pkg.go.dev/time) package,
with the one difference being duration values are represented as float values
(in seconds) instead of a dedicated duration type.

## Constants

Predefined layouts for use in `time.parse` and `time.format` include:

- ANSIC
- UnixDate
- RubyDate
- RFC822
- RFC822Z
- RFC850
- RFC1123
- RFC1123Z
- RFC3339
- RFC3339Nano
- Kitchen
- Stamp
- StampMilli
- StampMicro
- StampNano

### Example Constant Usage

```go copy filename="Example"
>>> time.parse(time.RFC3339, "2023-08-01T12:00:00-04:00")
time("2023-08-01T12:00:00-04:00")
```

## Functions

### now

```go filename="Function signature"
now() time
```

Returns the current time as a time object.

```go copy filename="Example"
>>> time.now()
time("2024-01-15T12:51:10-05:00")
```

### unix

```go filename="Function signature"
unix() time
```

Unix returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC

```go copy filename="Example"
>>> time.unix(1725885470, 0)
time("2024-09-09T14:37:50+02:00")
```

### parse

```go filename="Function signature"
parse(layout, value string) time
```

Parses a string into a time.

```go copy filename="Example"
>>> time.parse(time.RFC3339, "2023-08-07T21:19:27-04:00")
time("2023-08-07T21:19:27-04:00")
```

### since

```go filename="Function signature"
since(t time) float
```

Returns the elapsed time in seconds since the given time.

```go copy filename="Example"
>>> t := time.now()
>>> time.since(t)
1.864104666
```

### sleep

```go filename="Function signature"
sleep(duration float)
```

Sleeps for the given duration in seconds.

```go copy filename="Example"
>>> time.sleep(1)
```

## Types

### time

The `time` type represents a moment in time.

#### Methods

##### time.before

```go filename="Method signature"
before(t time) bool
```

Returns whether this time is before the given time.

```go copy filename="Example"
>>> t := time.parse(time.RFC3339, "2023-08-01T12:00:00-04:00")
>>> t.before(time.parse(time.RFC3339, "2023-08-02T00:00:00-04:00"))
true
```

##### time.after

```go filename="Method signature"
after(t time) bool
```

Returns whether this time is after the given time.

```go copy filename="Example"
>>> t := time.parse(time.RFC3339, "2023-08-01T12:00:00-04:00")
>>> t.after(time.parse(time.RFC3339, "2023-08-02T00:00:00-04:00"))
false
```

##### time.format

```go filename="Method signature"
format(layout string) string
```

Formats the time according to the given layout.

```go copy filename="Example"
>>> t := time.parse(time.RFC3339, "2023-08-01T12:00:00-04:00")
>>> t.format(time.RFC3339)
"2023-08-01T12:00:00-04:00"
>>> t.format(time.Kitchen)
"12:00PM"
>>> t.format(time.UnixDate)
"Tue Aug  1 12:00:00 EDT 2023"
```

##### time.utc

```go filename="Method signature"
utc() time
```

Returns the UTC time corresponding to this time.

```go copy filename="Example"
>>> t := time.parse(time.RFC3339, "2023-08-01T12:00:00-04:00")
>>> t.utc()
time("2023-08-01T16:00:00Z")
```

##### time.unix

```go filename="Method signature"
unix() int
```

Returns the number of seconds elapsed since the Unix epoch.

```go copy filename="Example"
>>> t := time.parse(time.RFC3339, "2023-08-01T12:00:00-04:00")
>>> t.unix()
1690905600
```


---
context/docs/modules/uuid.mdx
---
# uuid

Module `uuid` provides generation of the different flavors of UUIDs. The
generated UUIDs are returned as strings.

The core functionality is provided by
[github.com/gofrs/uuid](https://github.com/gofrs/uuid).

## Module

```go copy filename="Function signature"
uuid() string
```

The `uuid` module object itself is callable, which is a shorthand for `uuid.v4()`.

```go copy filename="Example"
>>> uuid()
"83650166-58e3-4077-91a1-f176199f4954"
```

## Functions

### v4

```go filename="Function signature"
v4() string
```

Returns a randomly generated v4 UUID.

```go filename="Example"
>>> uuid.v4()
"83650166-58e3-4077-91a1-f176199f4954"
```

### v5

```go filename="Function signature"
v5(namespace, name string) string
```

Returns a UUID based on SHA-1 hash of the namespace UUID and name.

```go filename="Example"
>>> uuid.v5("c54e4fe3-ced2-4d07-a373-a95da134685e", "test")
"cd0c3ed6-1143-5e9f-bdc7-dd32215bb7ea"
```

### v6

```go filename="Function signature"
v6() string
```

Returns a v6 UUID. The v6 UUID is a reordering of UUIDv1 fields so it is
lexicographically sortable by time.

```go filename="Example"
>>> uuid.v6()
"1ef0171d-c5fb-6d5c-955f-d006d0ab5f0c"
```

### v7

```go filename="Function signature"
v7() string
```

Returns a v7 UUID. The v7 UUID is time-ordered and embeds a Unix timestamp
with millisecond precision. The time-ordered aspect makes these IDs useful
in some database scenarios, since database performance may be improved as
compared to v4 UUIDs.

```go filename="Example"
>>> uuid.v7()
"018f0b0e-1841-7560-9ec9-fa3272646ac7"
```


---
context/docs/modules/vault.mdx
---
import { Callout } from 'nextra/components';

# vault

<Callout type="info" emoji="ℹ️">
  This module requires that Risor has been compiled with the `vault` Go build tag.
  When compiling **manually**, [make sure you specify `-tags vault`](https://github.com/risor-io/risor#build-and-install-the-cli-from-source).
</Callout>

Module `vault` provides a client to interact with Hashicorp Vault

## Functions

### connect

```go filename="Function signature"
connect(address string)
```

Instanciates a new client for the given Vault address

```go filename="Example"
client := vault.connect("http://127.0.0.1:8200")
client.token = "hvs.AJ71UUKBsv1jiW7pJljTz4BN"
```

### write

```go filename="Function signature"
write(data object, path string)
```

Writes the given object to the given path.

```go filename="Example"
client.write({"data": {"password1": "t0p$ecret", "password2": "cl@$$ified"}}, "/secret/data/foo")
```

### write_raw

```go filename="Function signature"
write_raw(data byte_slice, path string)
```

Writes the given data to the given path.

```go filename="Example"
client.write_raw(byte_slice('{"data": {"password1": "t0p$ecret", "password2": "cl@$$ified"}}'), "/secret/data/foo")
```

### read

```go filename="Function signature"
read(path string) object
```

Returns an object from the given path

```go filename="Example"
client.read("/secret/data/foo")
```

### read_raw

```go filename="Function signature"
read_raw(path string) object
```

Returns an HTTP response object from Vault from the given path

```go filename="Example"
client.read("/secret/data/foo")
```

### delete

```go filename="Function signature"
delete(path string) object
```

Deletes an object from the given path

```go filename="Example"
client.delete("/secret/data/foo")
```

### list

```go filename="Function signature"
list(path string) object
```

Returns a list objects from the given path

```go filename="Example"
client.list("/secret/data/foo")
```


---
context/docs/modules/yaml.mdx
---
# yaml

Module `yaml` provides YAML encoding and decoding.

## Functions

### marshal

```go filename="Function signature"
marshal(v object) string
```

Returns a YAML string representing the given value. Raises an error if the value
cannot be marshalled.

```go copy filename="Example"
>>> m := {one: 1, two: 2}
>>> yaml.marshal(m)
"one: 1\ntwo: 2\n"
```

### unmarshal

```go filename="Function signature"
unmarshal(s string) object
```

Returns the value represented by the given YAML string. Raises an error if the
string cannot be unmarshalled.

```go copy filename="Example"
>>> yaml.unmarshal("one: 1\ntwo: 2")
{"one": 1, "two": 2}
>>> yaml.unmarshal("{bad") // raises value error
```

### valid

```go filename="Function signature"
valid(s string) bool
```

Returns whether the given string is valid YAML.

```go copy filename="Example"
>>> yaml.valid("42")
true
>>> yaml.valid("{oops")
false
```


---
context/docs/types/_meta.json
---
{
  "overview": {
    "title": "Overview"
  },
  "numerics": {
    "title": "Numerics"
  },
  "string": {
    "title": "String"
  },
  "list": {
    "title": "List"
  },
  "map": {
    "title": "Map"
  }
}


---
context/docs/types/bool.mdx
---
# Bool

The `bool` type in Risor is a simple wrapper of the Go `bool` type.

All underlying object types in Risor implement the `object.Object` interface,
which includes `IsTruthy()` and `Equals(other)` methods. It's good to keep this
in mind since object "truthiness" can be leveraged in conditional statements.

```go
>>> bool(0)
false
>>> bool(5)
true
>>> bool([])
false
>>> bool([1,2,3])
true
>>> if 5 { print("5 is truthy") }
5 is truthy
>>> 5 == 5.0
true
>>> [1,2] == [1,2]
true
>>> [1,2] != [1,2]
false
>>> false == false
true
```

### Related Built-ins

#### bool(x)

Returns `true` or `false` according to the given objects "truthiness". Container
types including lists, maps, sets, and strings evaluate to `false` when empty
and `true` otherwise. Iterators are truthy when there are more items remaining
to iterate over. Objects of other types are generally always considered to
be truthy.


---
context/docs/types/list.mdx
---
# List

Lists in Risor behave very similarly to lists in Python. Methods and indexing
on lists are the primary way to interact with these objects. A list can store
objects of any types, including a mix of types in one list.

```go
>>> l := ["a", 1, 2]
["a", 1, 2]
>>> l.append("tail")
["a", 1, 2, "tail"]
```

## Container Operations

```go
>>> l := ["a", "b", "c"]
["a", "b", "c"]
>>> len(l)
3
>>> "c" in l
true
>>> "d" in l
false
>>> l[2]
"c"
>>> l[2] = "d"
>>> l
["a", "b", "d"]
>>> l[1:]
["b", "d"]
>>> l[:1]
["a"]
```

## Related Built-ins

### list(container)

Returns a new list populated with items from the given container. If a list is
provided, a shallow copy of the list is returned. It is also commonly used to
convert a set to a list.

```go
>>> s := {"a", "b", "c"}
{"a", "b", "c"}
>>> list(s)
["a", "b", "c"]
```

## Methods

### list.append(x)

Adds x to the end of the list.

### list.clear()

Empties all items from the list.

### list.copy()

Returns a shallow copy of the list.

### list.count(x)

Returns a count of how many times x is found in the list.

### list.extend(x)

Adds all items contained in x to the end of the list.

### list.index(x)

Returns the first index of x in the list, or -1 if not found.

### list.insert(index, x)

Inserts x into the list at the specified index.

### list.pop(index)

Removes the item at the given index from the list.

### list.remove(x)

Removes the first occurence of x in the list.

### list.reverse()

Reverses the list in place.

### list.sort()

Sorts the list in place.

### list.map(func)

Returns a transformed list, in which the given function is applied to each list item.

### list.filter(func)

Returns a transformed list, in which the given function returns true for items that should be added to the output list.

### list.each(func)

Calls the supplied function once with each item in the list.


---
context/docs/types/map.mdx
---
# Map

Maps associate keys with values and provide fast lookups by key. Risor
maps use underlying Go maps of type `map[string]interface{}`. This means
Risor maps always operate with string keys, which provides equivalence with JSON.

```go
>>> m := {one: 1, two: 2}
{"one": 1, "two": 2}
>>> m["three"] = 3
>>> m
{"one": 1, "three": 3, "two": 2}
```

## Container Operations

```go
>>> m := {"name": "sean", "age": 27}
{"age": 27, "name": "sean"}
>>> len(m)
2
>>> "age" in m
true
>>> m["age"]
27
>>> m["age"] = 28
>>> m
{"age": 28, "name": "sean"}
>>> m.keys()
["age", "name"]
```

## Related Built-ins

### delete(map, key)

Deletes the item with the specified key from the map. This operation has no
effect if the key is not present in the map.

### map(container)

Returns a new map with the contents of the given container. Generally, containers
are transformed into the map by creating an iterator for the given container and
the key and value for each iterator entry are added to the map. As a special
case, if the container is a list then it is expected to be a nested list of
key-value pairs, e.g. `[["key1", "val1"]]`. Any non-string keys that are
encountered are automatically converted to their string representation.

```go
>>> map({"a", "b", "c"})
{"a": true, "b": true, "c": true}
>>> map("abc")
{"0": "a", "1": "b", "2": "c"}
>>> map([["name", "joe"], ["age", 18]])
{"age": 18, "name": "joe"}
```

## Methods

### map.clear()

Removes all items from the map.

### map.copy()

Returns a shallow copy of the map, containing the same keys and values.

### map.get(key, default=nil)

Returns the value associated with the given key, if it exists in the map.
If the key is not in the map, the given default value is returned.

### map.items()

Returns a list of [key, value] pairs containing the items from the map.

### map.keys()

Returns a sorted list of keys contained in the map.

### map.pop(key, default=nil)

Returns the value associated with the given key and then removes it from the
map. If the key is not in the map, the given default value is returned instead.

### map.setdefault(key, default)

Sets the key to the given default value if the key is not already in the map.
If the key already is in the map, do nothing. Returns the value associated with
the key after the set action.

### map.update(other)

Updates this map with the key-value pairs contained in the provided map,
overwriting any items with matching keys already in this map.

### map.values()

Returns a sorted list of values contained in the map.


---
context/docs/types/numerics.mdx
---
# Numerics

Int and Float types are the two numeric types in Risor. They correspond to
boxed `int64` and `float64` values in Go. Risor automatically converts Ints
to Floats in mixed type operations.

The standard set of numeric operators are available when working with these types.

| Operation | Result                |
| --------- | --------------------- |
| x + y     | sum of x and y        |
| x - y     | difference of x and y |
| x \* y    | product of x and y    |
| -x        | negation of x         |
| x \*\* y  | x to the power of y   |
| x += y    | add y to x            |
| x -= y    | subtract y from x     |
| x \*= y   | multiply x by y       |
| x /= y    | divide x by y         |

```go
>>> x := 2
2
>>> y := 3
3
>>> x * y
6
>>> x + y
5
>>> type(x + y)
"int"
>>> type(x + float(y))
"float"
```

Many math functions are also available in the Risor `math` module.

### Related Built-ins

#### float(x)

Converts a String or Int object to a Float. An error is generated if the
operation fails.

```go
>>> float("4.4")
4.4
```

#### int(x)

Converts a String or Float to an Int. An error is generated if the operation
fails.

```go
>>> int(4.4)
4
>>> int("123")
123
```


---
context/docs/types/overview.mdx
---
import { Cards, Card } from 'nextra/components';

# Data Types

Risor includes a variety of built-in types. The core types are: int, float,
bool, error, string, list, map, set, result, function, and time. There are also
a handful of iterator types, one for each container type.

Container types may hold a heterogeneous mix of types within. There is not
currently a way to restrict the types a container may hold.

Optional type hints like found in Python or Typescript may be a future addition
to Risor.

## Quick Reference

```go
101         // int
1.1         // float
"1"         // string
[1,2,3]     // list
{"key":2}   // map
{1,2}       // set
false       // bool
nil         // nil
func() {}   // function
time.now()  // time
```

### Container Operations

Strings in Risor implement the `object.Container` interface, which means they
support typical container-style operations:

```go
>>> s := "hello"
"hello"
>>> s[0]
"h"
>>> len(s)
5
>>> s[1:3]
"el"
>>> s[1:]
"ello"
>>> s[:1]
"h"
>>> iter(s)
string_iter("hello")
>>> iter(s).next()
iter_entry(0, "h")
```


---
context/docs/types/set.mdx
---
# Set

Sets represent an unordered collection of unique objects. Only hashable objects
can be added to sets, which includes bool, int, float, nil, and string. It is
not possible to add a list or map to a set, since they are not hashable.

## Container Operations

```go
>>> s := {1, 2, 3}
{1, 2, 3}
>>> 3 in s
true
>>> 4 in s
false
>>> s[3]
true
>>> s[4]
false
>>> delete(s, 3)
>>> s
{1, 2}
```

## Related Built-ins

### delete(set, key)

Deletes the given key from the set. This is a no-op if the key is not present in the set.

### set(container)

Returns a new set that is populated with the contents of the given container.
The loading behavior for each provided type is as follows:

- Given a list, the values within are added to the set.
- Given a string, the characters within are added to the set.
- Given a map, the keys within are added to the set.

```go
>>> set([1, 2, 3, 3])
{1, 2, 3}
>>> set("abc")
{"a", "b", "c"}
>>> set({one: 1, two: 2})
{"one", "two"}
```

## Methods

### set.add(x)

Add `x` to the set. If `x` is not hashable, an error is generated.

### set.clear()

Empties all items from the set.

### set.remove(x)

Remove `x` from the set. This is a no-op if `x` is not in the set.

### set.union(other)

Returns a new set which contains the union of all items from this set
and the other set.

### set.intersection(other)

Returns a new set containing items that are present in both this set and the other set.


---
context/docs/types/string.mdx
---
# String

Strings in Risor are based on the underlying `string` type in Go. As such,
they support unicode and various operations like indexing operate on the
underlying runes within the string.

### Quote Types

There are three ways to quote strings in Risor source code:

```
'single quotes: supports interpolated {vars}'
"double quotes: equivalent to Go strings"
`backticks: raw strings that may span multiple lines`
```

The single quoted string approach offers string formatting via interpolation,
much like [f-strings](https://peps.python.org/pep-0498/) in Python. Arbitrary
Risor expressions can be embedded within parentheses and resolved during
evaluation. In Risor, the restriction on these expressions is that they
cannot contain curly braces, since those are used to mark the beginning and
end of the template expression.

An example with simple expressions:

```go
>>> name := "jean"
"jean"
>>> age := 30
30
>>> '{name} is {age} years old'
"jean is 30 years old"
```

Another example:

```go
>>> nums := [0, 1, 2, 3]
[0, 1, 2, 3]
>>> 'the max is {math.max(nums)} and the length is {len(nums)}'
"the max is 3 and the length is 4"
```

### Container Operations

Strings in Risor implement the `object.Container` interface, which means they
support typical container-style operations:

```go
>>> s := "hello"
"hello"
>>> s[0]
"h"
>>> len(s)
5
>>> s[1:3]
"el"
>>> s[1:]
"ello"
>>> s[:1]
"h"
>>> iter(s)
string_iter("hello")
>>> iter(s).next()
iter_entry(0, "h")
```

### Related Built-ins

#### chr(int)

Converts an Int to the corresponding unicode rune, which is returned as a String.
The `ord` built-in performs the inverse transformation.

#### ord(string)

Converts a unicode character to the corresponding Int value. The `chr` built-in
performs the inverse transformation. An error is generated if a multi-rune string is
provided.

#### sprintf(string, ...any)

Wraps `fmt.Sprintf` to format the string with the provided arguments. Risor
objects are converted to their corresponding Go types before being passed to
`fmt.Sprintf`.

#### string(x)

Returns the string representation of any Risor object.

### Methods

#### string.contains(s)

Returns a bool that indicates if `s` is a substring of this string.

#### string.has_prefix(s)

Checks whether the string begins with the prefix `s`.

#### string.has_suffix(s)

Checks whether the string ends with the suffix `s`.

#### string.count(s)

Returns the number of occurrences of `s` in this string.

#### string.join(list)

Return the joined result of the given list of strings, using this string
as the separator.

#### string.split(separator)

Splits this string on all occurrences of the given separator, returning
the resulting list of strings.

#### string.fields()

Splits this string on whitespace, returning the list of non-whitespace substrings. If this string is only whitespace, an empty list is returned.

#### string.index(s)

Returns the index of the first occurence of `s` in this string, or `-1`
if `s` is not present.

#### string.last_index(s)

Returns the index of the last occurence of `s` in this string, or `-1`
if `s` is not present.

#### string.replace_all(old, new)

Returns a copy of this string with all occurrences of `old` replaced by `new`.

#### string.to_lower()

Returns a copy of this string that is transformed to all lowercase.

#### string.to_upper()

Returns a copy of this string that is transformed to all uppercase.

#### string.trim(cutset)

Returns a copy of this string with all leading and trailing characters contained
in `cutset` removed.

#### string.trim_prefix(prefix)

Returns a copy of this string without the given prefix. This is a no-op if this
string doesn't start with `prefix`.

#### string.trim_space()

Returns a copy of this string without the leading and trailing whitespace.

#### string.trim_suffix(suffix)

Returns a copy of this string without the given suffix. This is a no-op if this
string doesn't end with `suffix`.


---
prompts/prompt.md
---
You are a Risor language programmer.

I gave you a list of .mdx files that explain how Risor is written. .mdx files are markdown files essentially.

The Risor language syntax is defined in context/docs/syntax.mdx. This is critical, pay attention to the syntax and don't invent new syntax.

Risor scripts have a .risor file extension

Risor has some similarities with Python, but it isn't Python. Don't try to use syntax not documented in all the .mdx files you have.

The Risor language built-ins are documented in context/docs/builtins.mdx
The official Risor modules available are documented in context/docs/modules, where each mdx file documents a module.
The official Risor types available are documented in context/docs/types, where each mdx file documents the built-in types.
Risor language rules are defined in context/rules.txt. Rules override everything else.

Your job is to write good, modular Risor code. Use two spaces to indent code.


---