A collection of utilities for working with the Koto runtime.



Provides access to the arguments that were passed into the script when running the koto CLI application.

If no arguments were provided then the list is empty.


# Assuming that the script was run with `koto script.koto -- 1 2 "hello"`
size koto.args
# 3
# 1
# hello


|Value| -> Value

Makes a copy of the value.

Shared mutable data

For values that have shared mutable data (i.e., List, Map), unique copies of the data will be made. Note that this only applies to the first level of data, so nested containers will still share their data with their counterparts in the original data. To make a copy where any nested containers are also unique, use koto.deep_copy.

Iterator copies

Copied iterators share the same underlying data as the original, but have a unique iteration position, which is part of an iterator's shared state by default.

If the iterator is a generator, some effort will be made to make the generator's copy produce the same output as the original. However, this isn't guaranteed to be successful. Specifically, the value stack of the copied virtual machine will be scanned for iterators, and each iterator will have a copy made. Iterators that may be used in other ways by the generator (such as being stored in containers or function captures) won't be copied and will still have shared state.


# Copying a map
x = {foo: -1, bar: 99}
y = x
y.foo = 42
# -> 42

z = koto.copy x
z.bar = -1
x.bar # x.bar remains unmodified due to the copy
# -> 99
# Copying a list

x = (1..=10).iter()
y = x # y shares the same iteration position as x.
z = koto.copy x # z shares the same iteration data (the range 1..=10),
                # but has a unique iteration position.

# -> 1
# -> 2
y.next().get() # y shares x's iteration position.
# -> 3
z.next().get() # z isn't impacted by the advancing of x and y.
# -> 1

See also


|Value| -> Value

Makes a unique deep copy of the value's data.

Shared mutable data

This makes a unique copy of the value's data, and then recursively makes deep copies of any nested containers in the value.

If only the first level of data needs to be made unique, then use koto.copy.


x = [[1, 2], [3, [4, 5]]]
y = koto.deep_copy x
y[1][1] = 99
x # a deep copy has been made, so x is unaffected by the assignment to y
# -> [[1, 2], [3, [4, 5]]]

See also


|| -> Map

Returns the current module's export map.

Although typically module items are exported with export expressions, it can be useful to export items programatically.


|Value| -> Value

Returns the value's hash as an integer, or Null if the value is not hashable.


from koto import hash

(hash 'hi') == (hash 'bye')
# -> false

# Lists aren't hashable
hash [1, 2] 
# -> null

# Tuples are hashable if they only contain hashable values 
(hash (1, 2)) == null
# -> false


|String| -> Chunk

Compiles the string as Koto code and returns a compiled Chunk on success, or throws if a compilation error occurs.


chunk = koto.load '1 + 2'
koto.run chunk
# -> 3

See also


|String| -> Value

Compiles and runs the provided Koto code, and returns the resulting value. Errors thrown while executing the code get rethrown.

|Chunk| -> Value

Runs the compiled Chunk, and returns the resulting value. Errors thrown while executing the chunk's bytecode get rethrown.


koto.run '[1, 2, 3, 4].sum()'
# -> 10

See also


String or Null

If a script is being executed then script_dir provides the directory that the current script is contained in as a String, otherwise script_dir is Null.


String or Null

If a script is being executed then script_path provides the path of the current script as a String, otherwise script_path is Null.


|Value| -> Integer

Returns the size of a value.

The size of a value is typically defined as the number of elements in a container, with some notable exceptions:

  • For strings, the size is number of bytes in the string data.
  • For ranges, the size is the number of integers in the range.
    • For non-inclusive ranges, this is equivalent to range.end() - range.start().
    • For inclusive ranges, this is equivalent to range.end() + 1 - range.start().
    • If the range is unbounded then an error will be thrown.
  • An error will be thrown if the value doesn't have a defined size.


from koto import size
(size [1, 2, 3]), (size (,))
# -> (3, 0)

(size 'hello'), (size 'héllø'), (size '')
# -> (5, 7, 0)

(size 10..20), (size 10..=20), (size 20..0)
# -> (10, 11, 20)


|Value| -> String

Returns the type of the input Value as a String.


koto.type true
# -> Bool

x = 42
koto.type x
# -> Int

foo =
  @type: "Foo"
koto.type foo
# -> Foo