utilities

args, classify, coalesce, compare, default, delete, evaluate, exists, input, invoke, load, max, min, parse, print, run, save, swap, throw, time, try, vargs


args

Syntax

args([@variables, ...])

Description

Assigns arguments to named variables. Pass a reference to a local variable for each argument your function expects. The caller of your function must pass exactly this number of arguments or an exception will be thrown.

Examples

args(@x, @y)

See Also

vargs


<classify>

Syntax

'class' = classify(<value>)

Description

Examines <value> and tries to determine what "value class" it belongs to:

- 'void' (empty string)
- 'boolean' (true or false)
- 'number' (starts with a digit, '-' or 'i' for "infinity", and is convertible to a number)
- 'reference' (starting with ':' and containing at least one more ':')
- 'function' (enclosed in '{ }' or begins with '>')
- 'native' (enclosed in '< >')
- 'string' (if no other match)

Examples

classify(void) == 'void'
classify('false') == 'boolean'
classify(123.456) == 'number'
classify(@localvar) == 'reference'
classify(function { }) == 'function'
classify(>lambda) == 'function'
classify('<print>') == 'native'
classify('tumbleweed') == 'string'

coalesce

Syntax

<value> = coalesce(<values> | @variables, ...)

Description

Returns the first <value> in the argument list that is non-void, or the contents of the first @variables that exists (whichever comes first).

Examples

coalesce(@mustBeDefined, '')
coalesce(cantBeEmpty, perhapsThisAintEmpty, 'nowIAmDefinitelyNotEmpty')

See Also

default, exists


compare

Syntax

<diff> = compare(<a>, <b>)

Description

Returns 0 if <a> equals <b>, -1 if <a> is less than <b> and 1 if <a> is greater than <b>. This function is useful in sorting algorithms.

Examples

compare('abc', 'def') < 0
compare('def', 'abc') > 0
compare('abc', 'abc') == 0

See Also

qsort, swap


default

Syntax

default(@variable, <value>)

Description

Assigns <value> to @variable if @variable does not exist. If it does already exist, this function does nothing. Use this function for example to initialize optional arguments.

Examples

default(@name, 'Smith')

See Also

coalesce


<delete>

Syntax

delete(@variable)

Description

Deletes the variable referenced to by @variable.

Notice that this function can only delete a single variable at a time. This means only a single "element" in a "container" as well. Use prune() to delete an entire "plain old data" container and destruct() to delete an object.

Examples

delete(@begone)
delete(@hurray[1972])

See Also

destruct, exists, prune


<evaluate>

Syntax

<result> = evaluate('code', [@frame])

Description

Evaluates 'code' and returns the result. You can decide which frame should execute the code by supplying a reference in @frame. Without @frame, code is executed in its own frame just as if you would call a function. Only the "frame identifier" of @frame is used, so you may for example pass a single ^ to evaluate code in the caller's frame.

Examples

evaluate('3 + 3') == 6
evaluate('x = random(1)', @x)

See Also

expand, invoke, parse, run


<exists>

Syntax

?found = exists(@variable)

Description

Returns true if the variable referenced to by @variable is defined.

Examples

exists(@::aglobal)
exists(@users['magnus lidstrom'])

See Also

coalesce, default, delete


<input>

Syntax

'answer' = input('question')

Description

Prints 'question' and returns a string read from standard input.

Examples

name = input("What's your name? ")

See Also

print


<invoke>

Syntax

invoke(['callee'], [>body], @args, [+offset = 0], [+count])

Description

Calls 'callee' (or >body) with the argument list @args. The difference between using 'callee' or >body is that the former should be a string with a function name, while the latter should be an actual function body. If both arguments are present, >body will be executed, but the called function's $callee variable will be set to 'callee'.

+offset can be used to adjust the element index for the first argument. +count is the number of arguments. If it is omitted, [@args].n is used to determine the count.

Examples

invoke('max', , @values)
invoke('(callback)', $0, @$, 1, 4)

See Also

evaluate, run


<load>

Syntax

'contents' = load('filePath')

Description

Loads a file from disk and returns it as a string. The standard implementation uses the file I/O of the standard C++ library, which takes care of line ending conversion etc. It can normally only handle ASCII text files.

Examples

data = load('myfolder/myfile.txt')

See Also

save


max

Syntax

<m> = max(<x>, <y>, [<z>, ...])

Description

Returns the largest value of all the arguments.

Examples

max(5, 3, 7, 1, 4) == 7
max('Sleepy', 'Grumpy', 'Happy', 'Bashful', 'Dopey', 'Sneezy', 'Doc') == 'Sneezy'
max('Zero', '10', '5') == 'Zero'

See Also

min


min

Syntax

<m> = min(<x>, <y>, [<z>, ...])

Description

Returns the smallest value of all the arguments.

Examples

min(5, 3, 7, 1, 4) == 1
min('Sleepy', 'Grumpy', 'Happy', 'Bashful', 'Dopey', 'Sneezy', 'Doc') == 'Bashful'
min('Zero', '10', '5') == '5'

See Also

max


<parse>

Syntax

+offset = parse('code')

Description

Parses 'code' (without executing it) and returns the number of characters that was successfully parsed. 'code' is expected to begin with a single PikaScript expression. The parsing ends when a semicolon or any unknown or unexpected character is encountered (including unbalanced parentheses etc). The resulting expression needs to be syntactically correct or an exception will be thrown.

You can use this function to extract PikaScript code inlined in other text.

Examples

parse('3+3') == 3
parse('1 + 2 * 3 ; stop at semicolon') == 10
parse(' /* leading comment */ code_here /* skip */ /* trailing */ /* comments */ but stop here') == 74
parse('stop after space after stop') == 5
parse('x + x * 3 ) * 7 /* stop at unbalanced ) */') == 10

See Also

evaluate, run


<print>

Syntax

print('textLine')

Description

Prints 'textLine' to the standard output, appending a newline character. (Sorry, but standard PikaScript provides no means for outputting text without the newline.)

Examples

print('Hello world!')

See Also

input


run

Syntax

run('filePath')

Description

Loads and executes a PikaScript source file. The code is executed in its own frame, just as if you were calling a function.

Examples

run('src/chess.pika')

See Also

evaluate


<save>

Syntax

save('filePath', 'contents')

Description

Saves 'contents' to a file (replacing any existing file). The standard implementation uses the file I/O of the standard C++ library, which takes care of line ending conversion etc. It can normally only handle ASCII text files.

Examples

save('myfolder/myfile.txt', 'No, sir, away! A papaya war is on!')

See Also

load


swap

Syntax

swap(@a, @b)

Description

Swaps the contents of the variables referenced to by @a and @b. This function is useful in sorting algorithms.

Examples

swap(@master, @slave)

See Also

compare, qsort


<throw>

Syntax

throw('error')

Description

Throws an exception. 'error' should describe the error in human readable form. Use try() to catch errors. (PikaScript exceptions are standard C++ exceptions. How uncaught exceptions are handled is up to the host application.)

Examples

throw('Does not compute')

See Also

try


<time>

Syntax

+secs = time()

Description

Returns the system clock as the number of seconds passed since January 1 1970 (or at least, if that is how the C time() function works on your platform).

Examples

elapsed = time() - lastcheck

<try>

Syntax

<result> = try(>doThis)

Description

Executes >doThis, catching any thrown exceptions and returning the error string of the exception. If no exception was caught, void is returned. The returned value of >doThis is discarded. (PikaScript exceptions are standard C++ exceptions. You may catch other exceptions than PikaScript errors with this function.)

Examples

success = try(>data = load(file))
try(>1+1) == void
try(>1+'a') == "Invalid number: 'a'"
try(>throw('catchme')) == 'catchme'

See Also

throw


vargs

Syntax

vargs([@arguments, ...], , [@optionals, ...])

Description

As args() but you may define arguments that are optional. The caller of your function must pass all required arguments or an exception will be thrown. An exception will also be thrown if the caller passes more optional arguments than present in vargs(). An easy way to assign default values for optional arguments is with the default() function. Alternatively you may want to use coalesce().

Examples

vargs(@required1, @required2, , @optional1, @optional2)

See Also

args, coalesce, default