Built-in Functions

Hymn has a number of functions useful for common routines, always available in each script. The function names are reserved words and cannot be overridden.

clear(object)	Removes all elements inside arrays and tables. Strings become blank
copy(object)	Copies all elements in an array or table and returns a new one
delete(object, index)	Deletes element at index in an array or table
echo value	Prints to standard out with a new line
exists(table, value)	Returns true if a given key exists in a table
float(value)	Casts a value to a float
index(object, value)	Returns the index number or table key for the given value
insert(object, index, value)	Inserts a value into an array at a given index
int(value)	Casts a value to an integer
keys(table)	Returns a sorted array of keys for a table
len(object)	Returns the length of an array or string, or size of a table
print(boolean, value)	Prints to standard out or standard error without a new line
push(object, value)	Adds a value to the end of an array
str(value)	Casts a value to a string
type(value)	Returns the value type as a string
SOURCE(value)	Returns a function's source code
OPCODES(value)	Returns a function's instruction codes
STACK	Returns the current stack
REFERENCE(value)	Returns a variable's reference counts
FORMAT(string)	Formats a string of source code

clear(object)

Removes all elements inside arrays and tables. Strings become blank.

>>> set array = [2, 4]
>>> clear(array)
>>> echo array
[]

copy(object)

Copies all elements in an array or table and returns a new one.

>>> set foo = [2, 4]
>>> set bar = copy(array)
>>> echo bar
[2, 4]

delete(object, index)

Deletes element at index in an array or table.

>>> set array = [2, 4]
>>> delete(array, 0)
>>> echo array
[4]
>>> set table = { foo: 8, bar: 16 }
>>> delete(table, "foo")
>>> echo table
{ bar: 16 }

echo value

Prints to standard out with a new line. Note that converting a table to a string will always sort the keys.

>>> set table = { c: 4, b: 2, a: 8 }
>>> echo table
{ a: 8, b: 2, c: 4 }

exists(table, value)

Returns true if a given key exists in a table.

>>> set table = { foo: none }
>>> echo exists(table, "foo")
true
>>> echo exists(table, "bar")
false

float(value)

Casts a value to a float.

>>> set x = 256
>>> echo float(x)
256.0

index(object, value)

Returns the index number or table key for the given value.

>>> set array = [2, 4, 8]
>>> echo index(array, 8)
2
>>> set table = { foo: 2, bar: 4 }
>>> echo index(table, 4)
bar

insert(array, index, value)

Inserts a value into an array at a given index.

>>> set array = [2, 4]
>>> insert(array, 1, 8)
>>> echo array
[2, 8, 4]

int(value)

Casts a value to an integer.

>>> set x = 256.1
>>> echo int(x)
256

keys(table)

Returns a sorted array of keys for a table.

>>> set table = { foo: 2, bar: 4 }
>>> echo keys(table)
["bar", "foo"]

len(object)

Returns the length of an array or string, or size of a table.

>>> set array = [2, 4, 8]
>>> echo len(array)
3
>>> set table = { "foo": 2, "bar": 4 }
>>> echo len(table)
2
>>> echo len("abc")
3

Prints to standard out or standard error without a new line. The 1st argument is evaluated as a boolean, where true means writing to standard error, and false means writing to standard out. The second value is evaluated to a string and printed.

>>> print(0, "This ")
>>> print(0, "is ")
>>> print(0, "ok")
This is ok
>>> print(1, "Error")
Error

push(array, value)

Adds a value to the end of an array.

>>> set array = [2, 4]
>>> push(array, 8)
>>> echo array
[2, 4, 8]

str(value)

Casts a value to a string.

>>> set x = 256
>>> set s = string(x)
>>> echo type(s)
string

type(value)

Returns the value type as a string.

>>> echo type(256)
integer
>>> echo type(256.0)
float
>>> echo type("256")
string

SOURCE(value)

Returns a function's source code.

>>> func foo(x) {
>>>   return x
>>> }
>>> echo SOURCE(foo)
func foo(x) {
  return x
}

OPCODES(value)

Returns a function's instruction codes.

>>> func foo(x) {
>>>   return x
>>> }
>>> echo OPCODES(foo)
0000    1 OP_GET_LOCAL: [1]
0002    | OP_RETURN

STACK

Returns the current stack.

>>> {
>>>   set x = 1
>>>   echo STACK()
>>> }
[function: script]
[integer: 1]

REFERENCE(value)

Returns a function's reference count.

>>> set x = {}
>>> set y = x
>>> echo REFERENCE(x)
3

FORMAT(value)

Formats a string of source code.

>>> set source = "2+4"
>>> echo FORMAT(x)
2 + 4

Back to Syntax Learn Libraries