# API reference

This page lists words that are provided by the Plorth interpreter itself. It does not include utilities provided by the Plorth runtime library.

## Global dictionary

### !=

- Takes:
- any, any
- Gives:
- boolean

Tests whether the two topmost values of the stack are not equal.

### -inf

- Gives:
- number

Pushes the value of negative infinity onto stack.

### 1array

- Takes:
- any
- Gives:
- array

Constructs array from given value.

### 2array

- Takes:
- any, any
- Gives:
- array

Constructs array from given two values.

### 2drop

- Takes:
- any, any

Discards the two topmost values from the stack.

```
1 2 3 2drop #=> 1
```

### 2dup

- Takes:
- any, any
- Gives:
- any, any, any, any

Duplicates two topmost values of the stack.

```
1 2 2dup #=> 1 2 1 2
```

### =

- Takes:
- any, any
- Gives:
- boolean

Tests whether the two topmost values of the stack are equal.

### >boolean

- Takes:
- any
- Gives:
- boolean

Converts the topmost value of the stack into a boolean. Null and false will become false while everything else will become true.

### >source

- Takes:
- any
- Gives:
- string

Converts the topmost value of the stack into a string that most accurately represents what the value would look like in source code.

### >string

- Takes:
- any
- Gives:
- string

Converts the topmost value of the stack into a string. Null will become an empty string.

### args

- Gives:
- array

Returns command line arguments given to the interpreter as an array of strings.

### array?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is an array.

### boolean?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is a boolean.

### clear

Clears the entire stack of current context.

### compile

- Takes:
- string
- Gives:
- quote

Compiles given string of source code into a quote.

### const

- Takes:
- any, string

Declares given value as constant in the current context with name identified by given string.

### depth

- Gives:
- number

Pushes current depth of the stack onto stack.

### drop

- Takes:
- any

Discards topmost value from the stack.

```
1 drop #=> empty stack
```

### dup

- Takes:
- any
- Gives:
- any, any

Duplicates the topmost value of the stack.

```
1 dup #=> 1 1
```

### e

- Gives:
- number

Pushes Euler's number onto stack.

### emit

- Takes:
- number

Outputs given Unicode code point into the standard output stream. Range error will be thrown if the given number is not a valid Unicode code point.

### error?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is an error.

### false

- Gives:
- boolean

Pushes the boolean value false onto stack.

### globals

- Gives:
- object

Returns the global dictionary as an object.

### if

- Takes:
- boolean, quote

Executes quote if the boolean value is true.

### if-else

- Takes:
- boolean, quote, quote

Calls first quote if boolean value is true, second quote otherwise.

### import

- Takes:
- string

Imports module from given path and adds all of its exported words into this execution context.

### inf

- Gives:
- number

Pushes the value of positive infinity onto stack.

### instance-of?

- Takes:
- any, object
- Gives:
- any, boolean

Tests whether prototype chain of given value inherits from given object.

### locals

- Gives:
- object

Returns the local dictionary of current execution context as an object.

### nan

- Gives:
- number

Pushes the value of NaN (not a number) onto stack.

### narray

- Takes:
- any..., number
- Gives:
- array

Constructs array from given amount of values from the stack.

### nip

- Takes:
- any, any
- Gives:
- any

Drops the first value and pushes the second value onto stack.

```
1 2 nip #=> 2
```

### nop

Does nothing. Can be used to construct empty quotes.

### now

- Gives:
- number

Returns the number of seconds that have elapsed since the Unix epoch (1 January 1970 00:00:00 UTC) rounded to the nearest integer.

### nread

- Takes:
- number
- Gives:
- string|null

Reads given number of Unicode characters from standard input stream and returns them in a string. If there is no more input to be read, null will be returned instead. The resulting string might have less than given number of characters if there isn't that much characters available from the standard input stream.

### null

- Gives:
- null

Pushes the null value onto stack.

### null?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is null.

### number?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is a number.

### object?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is an object.

### over

- Takes:
- any, any
- Gives:
- any, any, any

Copies second topmost value of the stack into topmost value of the stack.

```
1 2 over #=> 1 2 1
```

### pi

- Gives:
- number

Pushes the value of pi onto stack.

- Takes:
- any

Prints topmost value of the stack to stdout.

### println

- Takes:
- any

Prints the topmost value of the stack to stdout with a terminating new line.

### proto

- Takes:
- any
- Gives:
- any, object

Retrieves proto of the topmost value. If the topmost value of the stack is null, null will be returned instead.

### quote?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is a quote.

### range-error

- Takes:
- string|null
- Gives:
- error

Construct an instance of range error with given optional error message and places it on the stack.

### read

- Gives:
- string|null

Reads all available input from standard input stream, decodes it as UTF-8 encoded text and returns result. If end of input has been reached, null will be returned instead.

### rot

- Takes:
- any, any, any
- Gives:
- any, any, any

Rotates the three topmost values on the stack.

```
1 2 3 rot #=> 2 3 1
```

### string?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is a string.

### swap

- Takes:
- any, any
- Gives:
- any, any

Swaps positions of the two topmost values on the stack.

```
1 2 swap #=> 2 1
```

### symbol?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is symbol.

### true

- Gives:
- boolean

Pushes the boolean value true onto stack.

### try

- Takes:
- quote, quote

Executes first quote and if it throws an error, calls second quote with the error on top of the stack.

### try-else

- Takes:
- quote, quote, quote

Executes first quote and if it throws an error, calls second quote with the error on top of the stack. If no error was thrown, third quote will be called instead.

### tuck

- Takes:
- any, any
- Gives:
- any, any, any

Copies the topmost value of the stack as the third topmost value of the stack.

```
1 2 tuck #=> 2 1 2
```

### type-error

- Takes:
- string|null
- Gives:
- error

Construct an instance of type error with with given optional error message and places it on the stack.

### typeof

- Takes:
- any
- Gives:
- any, string

Returns name of the type of the topmost value as a string.

### unknown-error

- Takes:
- string|null
- Gives:
- error

Construct an instance of unknown error with with given optional error message and places it on the stack.

### value-error

- Takes:
- string|null
- Gives:
- error

Constructs an instance of value error with given optional error message and places it on the stack.

### version

- Gives:
- string

Returns version of the Plorth interpreter as string.

### while

- Takes:
- quote, quote

Executes second quote as long as the first quote returns true.

### word?

- Takes:
- any
- Gives:
- any, boolean

Returns true if the topmost value of the stack is word.

## array

### !

- Takes:
- any, number, array
- Gives:
- array

Sets value in the array at given index. Negative indices count backwards from the end. If the index is larger than the number of elements in the array, the value will be appended as the last element of the array.

### &

- Takes:
- array, array
- Gives:
- array

Set intersection: Returns a new array containing unique elements common to the two arrays.

### *

- Takes:
- number, array
- Gives:
- array

Repeats the array given number of times.

### +

- Takes:
- array, array
- Gives:
- array

Concatenates the contents of two arrays and returns the result.

### 2for-each

- Takes:
- quote, array, array

Runs quote taking two arguments once for each element pair in the arrays.

### 2map

- Takes:
- quote, array, array
- Gives:
- array

Applies quote taking two arguments once for each element pair in the arrays and constructs a new array from values returned by the quote.

### >quote

- Takes:
- array
- Gives:
- quote

Converts array into executable quote.

### @

- Takes:
- number, array
- Gives:
- array, any

Retrieves a value from the array at given numerical index. Negative indices count backwards from the end. If the given index is out of bounds, arange error will be thrown.

### every?

- Takes:
- quote, array
- Gives:
- array, boolean

Tests whether all elements in the array satisfy the provided testing quote.

### extract

- Takes:
- array
- Gives:
- any...

Extracts all values from the array and places them onto the stack.

### filter

- Takes:
- quote, array
- Gives:
- array

Removes elements of the array that do not satisfy the provided testing quote.

### find

- Takes:
- quote, array
- Gives:
- array, any|null

Returns the first element from the array that satisfies the provided testing quote. Otherwise null is returned.

### find-index

- Takes:
- quote, array
- Gives:
- array, number|null

Returns the index of the first element in the array that satisfies the provided testing quote. Otherwise null is returned.

### flatten

- Takes:
- array
- Gives:
- array

Creates new array with all sub-array elements concatted into it recursively.

### for-each

- Takes:
- quote, array

Runs quote once for every element in the array.

### includes?

- Takes:
- any, array
- Gives:
- array, boolean

Searches for given value in the array and returns true if it's included and false if it's not.

### index-of

- Takes:
- any, array
- Gives:
- array, number|null

Searches for given value from the array and returns its index in the array if it's included in the array and null if it's not.

### join

- Takes:
- string, array
- Gives:
- string

Concatenates all elements from the array into single string delimited by the given separator string.

### length

- Takes:
- array
- Gives:
- array, number

Returns the number of elements in the array, while keeping the array on the stack.

### map

- Takes:
- quote, array
- Gives:
- array

Applies quote once for each element in the array and constructs a new array from values returned by the quote.

### nflatten

- Takes:
- number, array
- Gives:
- array

Creates new array with all sub-array elements concatted into it recursively up to the given maximum depth.

### pop

- Takes:
- array
- Gives:
- array, any

Removes last element from the array and places it onto the stack.

```
[1, 2, 3] pop #=> [1, 2] 3
```

### push

- Takes:
- any, array
- Gives:
- array

Constructs new array where first value has been pushed as the last element of the existing array.

```
4 [1, 2, 3] push #=> [1, 2, 3, 4]
```

### reduce

- Takes:
- quote, array
- Gives:
- any

Applies given quote against an accumulator and each element in the array to reduce it into a single value.

### reverse

- Takes:
- array
- Gives:
- array

Reverses the array. The first array element becomes the last and the last array element becomes first.

### some?

- Takes:
- quote, array
- Gives:
- array, boolean

Tests whether any element in the array satisfies the provided quote.

### uniq

- Takes:
- array
- Gives:
- array

Removes duplicate elements from the array.

### |

- Takes:
- array, array
- Gives:
- array

Set union: Returns a new array by joining the two given arrays, excluding any duplicates and preserving the order of the given arrays.

## boolean

### ?

- Takes:
- any, any, boolean
- Gives:
- any

Selects between two values based on the boolean value. First value is returned when the boolean value is true and the second one is returned when it's false.

```
"greater" "less" 5 6 > ? #=> "less"
```

### and

- Takes:
- boolean, boolean
- Gives:
- boolean

Logical AND. Returns true if both values are true.

### not

- Takes:
- boolean
- Gives:
- boolean

Negates given boolean value.

### or

- Takes:
- boolean, boolean
- Gives:
- boolean

Logical OR. Returns true if either one of the values are true.

### xor

- Takes:
- boolean, boolean
- Gives:
- boolean

Exclusive OR.

## error

### code

- Takes:
- error
- Gives:
- error, number

Returns error code extracted from the error in numeric form.

### message

- Takes:
- error
- Gives:
- error, string|null

Returns error message extracted from the error, or null if the error does not have any error message.

### position

- Gives:
- error, error, object|null

Takes

Returns position in the source code where the error occurred, or null if no such information is available.

Position is returned as object with `filename`

, `line`

and `column`

properties.

### throw

- Takes:
- error

Sets given error as current error of the execution context.

## number

### %

- Takes:
- number, number
- Gives:
- number

Computes the modulo of the first number with respect to the second number i.e. the remainder after floor division.

### &

- Takes:
- number, number
- Gives:
- number

Performs bitwise and on the two given numbers.

### *

- Takes:
- number, number
- Gives:
- number

Performs multiplication on the two given numbers.

### +

- Takes:
- number, number
- Gives:
- number

Performs addition on the two given numbers.

### -

- Takes:
- number, number
- Gives:
- number

Subtracts the second number from the first and returns the result.

### /

- Takes:
- number, number
- Gives:
- number

Divides the first number by the second and returns the result.

### <

- Takes:
- number, number
- Gives:
- boolean

Returns true if the first number is less than the second one.

### <<

- Takes:
- number, number
- Gives:
- number

Returns the first value with bits shifted left by the second value.

### <=

- Takes:
- number, number
- Gives:
- boolean

Returns true if the first number is less than or equal to the second one.

### >

- Takes:
- number, number
- Gives:
- boolean

Returns true if the first number is greater than the second one.

### >=

- Takes:
- number, number
- Gives:
- boolean

Returns true if the first number is greater than or equal to the second one.

### >>

- Takes:
- number, number
- Gives:
- number

Returns the first value with bits shifted right by the second value.

### ^

- Takes:
- number, number
- Gives:
- number

Performs bitwise xor on the two given numbers.

### abs

- Takes:
- number
- Gives:
- number

Returns absolute value of the number.

### ceil

- Takes:
- number
- Gives:
- number

Computes the smallest integer value not less than given number.

### clamp

- Takes:
- number, number, number
- Gives:
- number

Clamps the topmost number between the minimum and maximum limits.

### finite?

- Takes:
- num
- Gives:
- number, boolean

Returns true if given number is finite.

### floor

- Takes:
- number
- Gives:
- number

Computes the largest integer value not greater than given number.

### in-range?

- Takes:
- number, number, number
- Gives:
- boolean

Tests whether the topmost number is in range of given minimum and maximum numbers.

### max

- Takes:
- number, number
- Gives:
- number

Returns maximum of two numbers.

### min

- Takes:
- number, number
- Gives:
- number

Returns minimum of two numbers.

### nan?

- Takes:
- number
- Gives:
- number, boolean

Returns true if given number is NaN.

### round

- Takes:
- number
- Gives:
- number

Rounds given number to nearest integer value.

### times

- Takes:
- quote, number

Executes a quote given number of times.

### |

- Takes:
- number, number
- Gives:
- number

Performs bitwise or on the two given numbers.

### ~

- Takes:
- number
- Gives:
- number

Flips the bits of the value.

## object

### !

- Takes:
- any, string, object
- Gives:
- object

Constructs a copy of the object with new named property either introduced or replaced.

### +

- Takes:
- object, object
- Gives:
- object

Combines the contents of two objects together and returns the result. If the two objects share keys the second object's values take precedence.

### @

- Takes:
- string, object
- Gives:
- object, any

Retrieves the value identified by given string from properties of the object. If the object does not have such a property, range error will be thrown. Notice that inherited properties are also included in the search.

### delete

- Takes:
- string, object
- Gives:
- object

Constructs a copy of the object with the named property removed.

### entries

- Takes:
- object
- Gives:
- object, array

Constructs an array of arrays where each non-inherited property in the object is represented as an pair (i.e. array containing two elements, one for the key and one for the value).

### has-own?

- Takes:
- string, object
- Gives:
- object, boolean

Tests whether the object has own property with given identifier. Inherited properties are not included in the search.

### has?

- Takes:
- string, object
- Gives:
- object, boolean

Tests whether the object has property with given identifier. Notice that inherited properties are also included in the search.

### keys

- Takes:
- object
- Gives:
- object, array

Retrieves all keys from the object and returns them in an array. Notice that inherited properties are not included in the list.

### new

- Takes:
- any...
- Gives:
- object

Constructs a new instance of the object and invokes its constructor if it has one with the newly constructed object pushed on top of the stack.

Type error will be thrown if the object has no "prototype" property.

### values

- Takes:
- object
- Gives:
- object, array

Retrieves all values from the object and returns them in an array. Notice that inherited properties are not included in the list.

## quote

### 2dip

- Takes:
- any, any, quote
- Gives:
- any, any

Temporarily hides two given values from the stack and calls given quote. Once the quote has returned from it's execution, hidden values will be placed back on the stack.

### >word

- Takes:
- symbol, quote
- Gives:
- word

Constructs word from given pair of symbol and quote.

### call

- Takes:
- quote

Executes the quote taken from the top of the stack.

### compose

- Takes:
- quote, quote
- Gives:
- quote

Constructs a new quote which will call the two given quotes in sequence.

### curry

- Takes:
- any, quote
- Gives:
- quote

Constructs a curried quote where given value will be pushed onto the stack before calling the original quote.

### dip

- Takes:
- any, quote
- Gives:
- any

Temporarily hides given value from the stack and calls given quote. Once the quote has returned from it's execution, hidden value will be placed back on the stack.

### negate

- Takes:
- quote
- Gives:
- quote

Constructs a negated version of given quote which negates the boolean result returned by the original quote.

## string

### *

- Takes:
- number, string
- Gives:
- string

Repeats the string given number of times.

### +

- Takes:
- string, string
- Gives:
- string

Concatenates the contents of the two strings and returns the result.

### >number

- Takes:
- string
- Gives:
- number

Converts string into a floating point decimal number, or throws a value error if the number cannot be converted into one.

### >symbol

- Takes:
- string
- Gives:
- symbol

Converts given string into symbol. Value error will be thrown if the string is empty or contains whitespace or non-symbolic characters such as separators.

### @

- Takes:
- number, string
- Gives:
- string, string

Retrieves a character at given index. Negative indices count backwards from the end of the string. If given index is out of bounds, a range error will be thrown.

### capitalize

- Takes:
- string
- Gives:
- string

Converts the first character of the string into upper case and the remaining characters into lower case.

### chars

- Takes:
- string
- Gives:
- string, array

Extracts characters from the string and returns them in an array of substrings.

### ends-with?

- Takes:
- string, string
- Gives:
- string, boolean

Tests whether end of the string is identical with the given substring.

### includes?

- Takes:
- string, string
- Gives:
- string, boolean

Tests whether the topmost string contains contents of the second string, returning true or false as appropriate.

### index-of

- Takes:
- string, string
- Gives:
- string, number|null

Searches for the first occurrence of a substring given as second topmost value of the stack from string given as topmost value of the stack. If the substring does not exist in the string, null will be returned. Otherwise, first numerical index of the occurrence is returned.

### last-index-of

- Takes:
- string, string
- Gives:
- string, number|null

Searches for the last occurrence of a substring given as second topmost value of the stack from string given as topmost value of the stack. If the substring does not exist in the string, null will be returned. Otherwise, last numerical index of the occurrence is returned.

### length

- Takes:
- string
- Gives:
- string, number

Returns the length of the string.

### lines

- Takes:
- string
- Gives:
- string, array

Extracts lines from the string and returns them in an array.

### lower-case

- Takes:
- string
- Gives:
- string

Converts the string into lower case.

### lower-case?

- Takes:
- string
- Gives:
- string, boolean

Tests whether the string contains only lower case characters. Empty strings return false.

### reverse

- Takes:
- string
- Gives:
- string

Reverses the string.

### runes

- Takes:
- string
- Gives:
- string, array

Extracts Unicode code points from the string and returns them in an array of numbers.

### space?

- Takes:
- string
- Gives:
- string, boolean

Tests whether the string contains only whitespace characters. Empty strings return false.

### starts-with?

- Takes:
- string, string
- Gives:
- string, boolean

Tests whether beginning of the string is identical with the given substring.

### swap-case

- Takes:
- string
- Gives:
- string

Turns lower case characters in the string into upper case and vice versa.

### trim

- Takes:
- string
- Gives:
- string

Strips whitespace from the begining and the end of the string.

### trim-left

- Takes:
- string
- Gives:
- string

Strips whitespace from the begining of the string.

### trim-right

- Takes:
- string
- Gives:
- string

Strips whitespace from the end of the string.

### upper-case?

- Takes:
- string
- Gives:
- string, boolean

Tests whether the string contains only upper case characters. Empty strings return false.

### words

- Takes:
- string
- Gives:
- string, array

Extracts white space separated words from the string and returns them in an array.

## symbol

### call

- Takes:
- symbol

Resolves given symbol into word or value, depending on the contents of the data stack, local dictionary and global dictionary and executes it. If the symbol does not resolve into any kind of word or value, number conversion is attempted on it. If that also fails, reference error will be thrown.

### position

- Takes:
- symbol
- Gives:
- symbol, object|null

Returns position in source code where the symbols was encountered, or null if no such information is available. If symbol caching has been enabled in the interpreter, source code position is not stored in symbols.

Position is returnedd as object with `filename`

, `line`

and `column`

properties.

## word

### call

- Takes:
- word

Executes body of the given word.

### define

- Takes:
- word

Inserts given word into current local dictionary.

### quote

- Takes:
- word
- Gives:
- word, quote

Extracts quote which acts as the body of the word and places it onto top of the stack.

### symbol

- Takes:
- word
- Gives:
- word, symbol

Extracts symbol from the word and places it onto top of the stack.