args, classify, coalesce, compare, default, delete, evaluate, exists, input, invoke, load, max, min, parse, print, run, save, swap, throw, time, try, vargs
args([@variables, ...])
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.
args(@x, @y)
'class' = classify(<value>)
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)
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'
<value> = coalesce(<values> | @variables, ...)
Returns the first <value> in the argument list that is non-void, or the contents of the first @variables that exists (whichever comes first).
coalesce(@mustBeDefined, '')
coalesce(cantBeEmpty, perhapsThisAintEmpty, 'nowIAmDefinitelyNotEmpty')
<diff> = compare(<a>, <b>)
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.
compare('abc', 'def') < 0
compare('def', 'abc') > 0
compare('abc', 'abc') == 0
default(@variable, <value>)
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.
default(@name, 'Smith')
delete(@variable)
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.
delete(@begone)
delete(@hurray[1972])
<result> = evaluate('code', [@frame])
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.
evaluate('3 + 3') == 6
evaluate('x = random(1)', @x)
?found = exists(@variable)
Returns true if the variable referenced to by @variable is defined.
exists(@::aglobal)
exists(@users['magnus lidstrom'])
'answer' = input('question')
Prints 'question' and returns a string read from standard input.
name = input("What's your name? ")
invoke(['callee'], [>body], @args, [+offset = 0], [+count])
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.
invoke('max', , @values)
invoke('(callback)', $0, @$, 1, 4)
'contents' = load('filePath')
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.
data = load('myfolder/myfile.txt')
<m> = max(<x>, <y>, [<z>, ...])
Returns the largest value of all the arguments.
max(5, 3, 7, 1, 4) == 7
max('Sleepy', 'Grumpy', 'Happy', 'Bashful', 'Dopey', 'Sneezy', 'Doc') == 'Sneezy'
max('Zero', '10', '5') == 'Zero'
<m> = min(<x>, <y>, [<z>, ...])
Returns the smallest value of all the arguments.
min(5, 3, 7, 1, 4) == 1
min('Sleepy', 'Grumpy', 'Happy', 'Bashful', 'Dopey', 'Sneezy', 'Doc') == 'Bashful'
min('Zero', '10', '5') == '5'
+offset = parse('code')
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.
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
print('textLine')
Prints 'textLine' to the standard output, appending a newline character. (Sorry, but standard PikaScript provides no means for outputting text without the newline.)
print('Hello world!')
run('filePath')
Loads and executes a PikaScript source file. The code is executed in its own frame, just as if you were calling a function.
run('src/chess.pika')
save('filePath', 'contents')
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.
save('myfolder/myfile.txt', 'No, sir, away! A papaya war is on!')
swap(@a, @b)
Swaps the contents of the variables referenced to by @a and @b. This function is useful in sorting algorithms.
swap(@master, @slave)
throw('error')
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.)
throw('Does not compute')
+secs = time()
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).
elapsed = time() - lastcheck
<result> = try(>doThis)
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.)
success = try(>data = load(file))
try(>1+1) == void
try(>1+'a') == "Invalid number: 'a'"
try(>throw('catchme')) == 'catchme'
vargs([@arguments, ...], , [@optionals, ...])
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().
vargs(@required1, @required2, , @optional1, @optional2)