use builtins

Dependencies: _builtins, `:::phoo

This module contains the words necessary to implement the builtin functionality of Phoo, that are defined in Phoo code.

The words that this module depends upon can be found on the page for _builtins (note the underscore).

#pragma flag value ( → )

Sets the control parameter flag specified to the specific value.

Example:

#pragma strictMode false // disables strict mode.
#pragma maxDepth 32 // sets the maximum recursion depth to 32 nested arrays.

in_scope block ( → )

Runs the code with a new entry on the scope stack.

noop ( → )

A no-op.

alias x y ( → )

Aliases x to mean y.

const ( → v )

Precomputes a value. (#6 - doesn’t work).

now! ( → )

Runs code during compilation. (#6 - doesn’t work).

// ( → )

Line comment (#6 - doesn’t work).

dup ( a → a a )

Duplicates top item.

over ( b a → b a b )

Copies second item to top.

swap ( b a → a b )

Swaps top two.

rot ( a b c → b c a )

Pulls third to top.

unrot ( a b c → c a b )

Pushes top down to third.

nip ( a b → b )

Removes second stack item.

tuck ( a b → b a b )

Copies first item to third.

2dup ( a b → a b a b )

dups two items as a pair.

2drop ( a b → )

drops two items as a pair.

2swap ( a b c d → c d a b )

swaps two pairs of items.

2over ( a b c d → a b c d a b )

overs two pairs of items.

pack ( *a n → a )

Takes n and then puts n items into an array.

unpack ( a → i j k ... )

Reverse of pack, it flattens an array onto the stack.

dip op ( a → a )

Takes the top item off the main stack, runs the block, and puts the item back.

abs ( n → |n| )

Absolute value of a number.

- ( a b → a-b )

Subtracts top from second.

/~ ( a b → floor(a/b) )

Flooring division.

mod ( a b → a%b )

Modulo.

!= ( a b → t )

Not equals.

<= ( a b → a<=b )

Less than or equal to.

< ( a b → a<b )

Less than.

>= ( a b → a>=b )

Greater than or equal to.

min ( a b → v )

Lesser of two value.

max ( a b → v )

Larger of two value.

clamp ( l u x → v )

Clamps x to $l\gte x\gt u$.

within ( l u x → t )

True if $l\gte x\gt u$.

$< ( s1 s2 → s1<s2 )

True if s1 comes before s2 in the dictionary.

$> ( s1 s2 → s1>s2 )

True if s1 comes after s2 in the dictionary.

not ( t → t )

Boolean inverse.

and ( t t → t )

Boolean and.

or ( t t → t )

Boolean or.

xor ( t t → t )

Boolean xor.

>> ( a n → b )

Shift a right by n places.

bit ( n → b )

$2^n$.

var name ( → )

Declares a new variable, initialized to undefined.

var, name ( v → )

Declares a new variable, initialized to top stack value.

is name ( v → )

Puts a value into a variable.

A note here on variables…

Under the hood, what var and var, do is dynamically define two new words, one being a stack called var_name which holds the value, and another one :name that looks up the variable. is simply tacks on “var_” to the name passed to it, which gets the stack, and then replaces the top item.

var foo desugars into:

to var_foo [ stack undefined ]
to :foo [ var_foo copy ]

And is foo:

var_foo replace

stack ( → a )

Placed at the start of a word, makes the word an ancillary stack.

release ( a → )

Removes the first item from an array and discards it. Mutates the array.

copy ( a → i )

Copies the last item of the array a onto the stack.

replace ( i a → )

Replaces the last item on the array a with i.

replace ( a b → )

Moves the last item from the array b to the array a.

tally ( n a → )

Adds n to the last item of the array a.

temp ( → a )

Temp is a general purpose ancillary stack.

done ( → )

Jumps immediately to the end of the array.

Example:

[ foo bar done baz ]
// foo bar will run, baz will not

again ( → )

Jumps immediately to the start of the array.

Example:

[ foo bar again baz ]
// foo bar will run infinitely

if ( t → )

If the top of stack is false, skips the next item.

Example:

[ foo bar if baz ]
// if bar returns false, baz will be skipped

iff ( t → )

If the top of stack is false, skips the next two items.

Example:

[ foo iff bar baz ]
// if foo returns false, bar baz will be skipped

else ( → )

Unconditionally skips the next item.

Example:

[ foo else bar baz ]
// bar will not run.

until ( t → )

If the top of stack is false, jumps back to the start of the array.

Example:

[ foo bar baz until ]
// repeats foo bar baz until baz returns true.

while ( t → )

If the top of stack is false, jumps to the end of the array.

Example:

[ foo while baz again ]
// runs foo at least once, then repeats bar foo until foo returns false

switch ( v → )

Begins a switch staement: puts the value to be switched upon in a temporary stack (not temp).

See Also: case, default

default ( v → )

Ends a switch staement: empties the switch value from the stack it is stored on.

See Also: switch, case

case action ( v → )

If the value on the stack is not the switch value, skips action. If it is, runs action and then jumps to the end of the array (skipping the other cases and the default).

See Also: switch, default

How to write switches…

The Phoo switch construct is versatile, allowing many different arrangements of its parts. By far the simplest is this:

switch do
    1 case do
        // do something if it was 1
    end
    2 case do
        // if it was 2
    end
    default do
        // if it was none of the options
    end
end

That, of course, is the nicely formatted option, however, this will suffice:

    // ... rest of block above
    switch
    1 case do
        // do something if it was 1
    end
    2 case do
        // if it was 2
    end
    default
    // if it was none of the options
end

Notice that the switch and default need not have a block after them; they serve only to initialize and clean up the ancillary stack that the value to be switched on is temporarily stored on. However, everything after the default is considered “the default action”, because the behavior of case when it matches is to run the item immediately following it, and then skip all of the items following the case block (to skip any number of subsequent cases and the default).

' value ( → v )

Puts the value following it on the stack instead of running it.

Example:

[ 1 2 3 ] // results in 3 items on the stack
' [ 1 2 3 ] // results in 1 item, the array [1, 2, 3]

run ( c → )

Runs the item on the stack as code.

this ( → a )

Puts a reference to the current array on the stack.

table ( n → i )

Placed at the start of a word, turns it into a lookup table. Takes the n-th item after the table and puts it on the stack, and then skips everything after it.

recurse ( → )

Causes the current array to run itself again.

times block ( n → )

Runs block the specified number of times.

i ( → n )

Inside of a times loop, gets the number of iterations left to do after this one.

i^ ( → n )

Inside of a times loop, gets the number of iterations done since the loop started.

j ( → n )

Inside of a doubly nested times loop, gets the number of iterations left to do in the outer loop after this one.

j^ ( → n )

Inside of a doubly nested times loop, gets the number of iterations done by the outer loop since the loop started.

range ( n → a )

Returns an array a containing all the integers from 0 up to n-1.

nrange ( n m → a )

Returns an array a containing all the integers from n up to m-1.

step ( n → )

Adds n to the current times loop’s iteration counter.

restart ( → )

Sets the current times loop’s iteration counter to the original value it started at, restarting the loop.

break ( → )

Sets the current times loop’s iteration counter to 0, causing the loop to end after this iteration is done.

printable ( c → t )

Given a character c, returns true or false whether it is in the printable non-whitespace region of ASCII (i.e. greater than 32).

trim ( s → t )

Trims the leading whitespace from a string.

nextword ( sstring → rremainder of string wfirst word )

Given a string that does not start with whitespace, returns the first word and the rest of the string.

split$ ( s → a )

Splits a string s into an array a of individual words.

nested ( i → a )

Puts an item in its own array.

len ( a → l )

Gets the length of the array or string.

pluck ( a n → a i )

Pulls the n-th item out of the array a and returns the shortened array and the item i.

See Also: stuff

stuff ( a i n → a )

Reverse of pluck, it puts the item back.

behead ( a → a i )

Returns the first item of the array a, and the rest. The original array is not mutated.

join ( a b → ab )

Joins two arrays or strings, selecting between ++ and concat depending on the type of the arguments.

of ( x n → a )

Makes an array with n x‘s in it.

reverse ( arr → rra )

Reverses the array.

reverse$ ( x → x )

reverse but for strings.

reflect ( x → x )

reverse but digs down into sub-arrays and reflects them too.

makewith ( c → l )

Places the code in a loop and returns the generated code.

The returned code takes an array or string on the stack and calls the original code passed to makewith with each item of the array or string.

witheach block ( a → )

Takes an array or string and runs block for each item in it.

fold ( a r → s )

Takes a function and an array and reduces the array by calling the function with pairs of the items from the array: (supposing k is the function)

' [ 1   2   3   4   5   6   7   8   9   0 ] ' k fold
    |   |   |   |   |   |   |   |   |   |
    '>k<'   |   |   |   |   |   |   |   |
      '-->k<'   |   |   |   |   |   |   |
          '-->k<'   |   |   |   |   |   |
              '-->k<'   |   |   |   |   |
                  '-->k<'   |   |   |   |
                      '-->k<'   |   |   |
                          '-->k<'   |   |
                              '-->k<'   |
                                  '-->k<'
                                      |
                                      result.

foldr ( a r → s )

Same as fold but applies the operation in reverse order.

map ( a r → s )

Passes each item of array a through function r and concatentates the returned values.

filter ( a r → s )

Passes each item of array a through function r and returns the items for which r returns true.

split ( a n → x y )

Splits the array between the n-th and n+1-th items and returns the parts, second half on top.

matchitem ( aarray to search fcriteria function to test if item matches ccleanup function to clean the stack → i )

Uses the provided functions to find an item. returns the index of the first found item.

find ( a x → i )

Finds the first index where item x occurs in the array a.

findwith criteria cleanup ( a → i )

Same as matchitem but uses lookahead for cleanup and criteria.

found? ( a i → t )

True if i is a valid index into array a.

Example:

to has-foo? [ dup $ "foo" find found? ]

lower ( s → s )

Turns a string lowercase.

upper ( s → s )

Turns a string uppercase.

++ ( s1 s2 → s1s2 )

Concatenates 2 items after casting both to string type.

num>$ ( x n → s )

Writes number x in base n.

$>num ( s n → x )

Parses string s as a number in base n.

big ( n → b )

Turns number n into a BigInt.

unbig ( b → n )

Reverse of big, it coerces a bigint back to a number.

sortwith comp ( a → s )

Using comparator comp, sorts the array. Does not mutate the array.

sort ( a → s )

Sort an array of numbers.

sort$ ( a → s )

Sort an array of strings.

try block ( → )

Runs block, and if it threw an error, silences the error and puts it on the try.err stack.

except block ( → )

If there is an error on the try.err stack, takes it and runs the block. If there is none, skips block.

exceptt block block ( → )

Like except, but it runs or skips two blocks instead of one.

How to use try and except

try forms the error-suppressing part, and except detects the error and runs the cleanup code. try and except/exceptt were designed after Python, and compare heavily:

try:
    doSomethingThatMayFail()
finally:
    alwaysDoThis()
except Exception as e:
    cleanUpError(e)
else:
    noErrorOccurred()

Phoo code translates one-for-one into this:

try doSomethingThatMayFail
alwaysDoThis
exceptt cleanUpError
else noErrorOccurred

Notice that there is no finally word; the process is simply to delay handling of the error until the alwaysDoThis code is run.

nestdepth ( → n )

Puts the current recursion depth on the stack.

stacksize ( → n )

Puts the number of items on the stack, on the stack.

to-do ( → a )

To-do is a general purpose ancillary stack.

new-do ( a → )

Initializes the stack a as a to-do stack by putting done on it.

add-to ( xxx* c n a → )

Puts the action c and its arguments xxx* (the number of which is n) on the to-do stack a.

now-do ( a → )

Runs all the queued items on the to-do stack, until it hits the done put there by new-to.

do-now ( a → )

Same as now-do but does the items in reverse order.

not-do ( a → )

Removes all the queued items from the to-do stack a without running them.

chr ( n → s )

Returns the character with the Unicode code point n.

ord ( s → n )

Reverse of chr, it gets the code point of the character.

isa? ( a s → t )

True if item a‘s type is the same as s.

isoneof ( a ss → t )

Same as isa? but accepts an array of types, which will succeed if any of them is the type of a.

stringify ( a → s )

Converts a to a string.

arrayify ( x → a )

Converts a to an array.

phoo ( c → )

Compile and run the code.

new@ ( f → o )

Constructs the function f by calling it with no arguments.

call@ ( f → r )

Calls the function f with no arguments.

!!todo!! ( → )

Throws 'todo'.

use path/to/module ( → )

Imports the module, skipping if it was already imported.

reuse path/to/module ( → )

Imports the module, force-reloading it even if it is already loaded.

dir ( → a )

Returns a list of the names of all the available words in this scope.

__name__ ( → s )

Gets the name of the current thread running. Implementation-dependent.

back to index

docs@04547c7