api.md

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.

---

print

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.