PDScript/BGB-Script Base Spec

Written: 2005-04-23
Update: 2005-04-23


Statements


Here, a block will refer to either a single statement or group of statements enclosed in braces.

break [<number>];
break. number will optionally give a number of break levels to skip over.

continue [<number>];
continue. number will optionally give a number of break levels to skip over.

goto <name>;
goto a label given by name.

throw <name>;
throw an exception given by name.

return;
return <EXPR>;
return from a function with a given value. the form absent a value by defualt returns NULL.

<name>:    label.

begin_object <EXPR> <BLOCK>
execute block within the context of the object given by expr.


function <name>(<VARS>) <BLOCK>
defines a new function in the object scope.

lfunction <name>(<VARS>) <BLOCK>
defines a new function in the lexical scope.


macro_statement <name>(<VARS>) <BLOCK>
defines a new statement macro.

macro_expression <name>(<VARS>) <BLOCK>
defines a new expression macro.


if(<EXPR>)<BLOCK> [else <BLOCK>]

begin <BLOCK>
naturally execute block once, however break and continue may be used to exit or loop within block.

while(<EXPR>)<BLOCK>
a while loop.

for(<EXPR>; <EXPR>; <EXPR>)<BLOCK>
a for loop.

let <name>(VARS) <BLOCK>
let, non-working

switch(<EXPR>) {<branches>}
switch statement.

try <BLOCK> [catch <name> <BLOCK>]*
executes a block and catch an exception of a given name, in which case the handler block will be executed.


var <VARS>
define vars in the object scope.

dynvar <VARS>
define vars in the dynamic scope.

local <VARS>
define vars in the lexical scope.


Expressions


Precedence


Precedence order and the set of operators differ a little from C and other similar languages.

Lit:	Literal values/builtin expressions
PE: (<expr>) <expr>[<ARGS>] <expr>.<name>
IncDec: ++<name> --<name> + - ! ~ ... <name>++ <name>--
<expr>(<ARGS>)
E: <expr>**<expr>
MD: * / % \ &
AS: + - | ^
SHLR: << >>
RCmp: < > <= >= == != <=> <<== >>== ===
Lop: &&
Lop2: || ^^
TCond: <expr>?<expr>:<expr>
Attr: := :!= :< :> :<= :>= :<< :>> :<<= :>>=
Equals: = += -= *= /= \= %= &= |= ^= >>= <<=

Operator Notes
<< and >>, when used with pointers or other objects, will compare by pointer value.
< and >, when used on strings and other types, compare by value.
<<== and >>==, pointer comparrision operators.
===: hard identity, compares by pointer vs == which may compare by value.

&& and || don't use short circuiting at present, so code should be careful of this.
^^ is a logical xor operator.

:= defines an attribute, which is a kind of first-class equality used for passing arguments about things.

:!=, :<, ... are attributes defining a logical relation between the name and the value. These may eventually be used in tasks such as queries or some kinds of constraints.


Literals


$<name>

#<name>    symbol
#:<name>    keyword
#{<ARGS>}    matrix
#[<ARGS>]    vector
#(<ARGS>)    complex

{<ARGS>}    array
[<ARGS>]    dictionary
[:<ARGS>:]    list
-<NUMBER>    negative number

lambda [<name>](<VARS>) <BLOCK>
fun [<name>](<VARS>) <BLOCK>
define a first-class function. name may be used to allow recursive forms, and will be visible only within the lexical scope of the block.

withcc(<name>) <BLOCK>
new continuation. BLOCK is executed with the continuation bound to name.

begin_object <EXPR> <BLOCK>
execute block within the context of the object given by expr.

quote_xml <XML>
treats a chunk of xml as if it were a parse tree.

xml <XML>
creates a glob of xml to be used as a value.

statement <BLOCK>
represents a statement in expresion position (intended primarily for macros).

quote(<EXPR>)
quote <BLOCK>
quote a statement or expression, generating a value that can be used in working with syntax.

<name>    var reference.
<number>    numeric literal.
<string>    string literal.
<charstr>    character literal.


Builtins


true: boolean true value
false: boolean false value
null: null value

system.io.print(...)
    print items

system.io.println(...)
    print items with trailing linebreak

system.interp.eval_block(block, self)
    evaluates a block of statements

system.interp.eval_expr(expr)
    evaluates an expression and returns result

system.interp.load(name[, toplevel])
    load and run a script

system.math.vector(<number+>)
    creates a numeric vector

system.math.normalize(vector)
    normalize a vector

system.basic.tostring(obj, ...)
    convert an object to a string

system.basic.copy(obj)
    copy an object

system.basic.flatten_xml(obj)
    convert an object to an xml representation.


system.basic.builtin_join(obj)
    try to fetch a value from an object, otherwise returns NULL.

system.basic.gettypename(obj)
    fetch type name for obj

system.basic.apply(fun, args[, self])
    apply a function to an array containing args. self is optionally the toplevel to use during the apply.

system.basic.buildxml(...)
    build a chunk of xml


system.system.usedheap()
    gets number of used cells on heap

system.system.freeheap()
    gets number of free cells on heap

system.system.deltaheap()
    heap size delta since last call

system.system.time()
    gets the current time in seconds


system.store.loadimage(name)
    Load objects from an image and return the root object.

system.store.saveimage(name, object)
    Save objects to an image.

Math

system.math.PI: Constant PI
system.math.E: Constant Epsilon
system.math.CI: Constant Complex I, #(0, 1)
system.math.CJ: Constant Complex J, #(0, 0, 1)
system.math.CK: Constant Complex K, #(0, 0, 0, 1)

system.math.sqrt(x): square root

system.math.floor(x): round down
system.math.ceil(x): round up
system.math.round(x): round nearest
system.math.truncate(x): fractional part

system.math.pow(x, y): raise x to y
system.math.degrees(x): radians to degrees
system.math.radians(x): degrees to radians

system.math.cos(x): cosine
system.math.sin(x): sine
system.math.tan(x): tangent

system.math.cos_d(x): cosine degrees
system.math.sin_d(x): sine degrees
system.math.tan_d(x): tangent degrees

system.math.acos(x): arc cosine
system.math.asin(x): arc sine
system.math.atan(f[, g]): arc tangent

system.math.ln(x): natural log
system.math.log(x[, b]):logarithm
system.math.log10(x): log 10

Operators

a===b        a IS b

a<b        Less
a>b        Greater

a<=b        LessEqual
a>=b        GreaterEqual
a==b        Equal
a!=b        NotEqual
a<=>b        Match

a&&b        Logical And
a||b        Logical Or
a^^b        Logical Xor

!a        Logical Not

a+b        Add Array Array => Array of combined contents
a+b        Add Array Integer => Array with b added to the base
a-b        Sub Array Integer => Array with b subtracted from the base

a+b        Add Functions, creates a linked function which will evaluate the first (leftmost) matching function first.

Number

a+b    Add
a-b    Subtract
a*b    Multiply
a/b    Divide
a\b    Integer Division
a%b    Modulus
a**b    Exponent

a<<b    Shift Left
a>>b    Shift Right

a&b    Bitwise And
a|b    Bitwise Or
a^b    Bitwise Xor

~a    Bitwise Not
-a    Negatation

Vector

a+b    Add Vector
a-b    Subtract Vector
a*b    Scale Vector
a/b    Divide Vector by scalar
a%b    Cross Product
a^b    Cross Product

-a    Negate Vector
|a    Vector Length
\a    Normalize Vector

Complex

+ Add Complex
- Subtract Complex
* Multiply Complex
/ Divide Complex

Matrix

a+b    Add Matrix
a-b    Subtract Matrix
a*b    Multiply Matrix
a/b    Multiply Matrix by iverse of B (a*(/b))

/a    Invert Matrix


Language Features


File IO

system.io.openfile(name, mode)
Open a specified file for io, returns file.

'mode' is a string containing chars that control the file mode.

r/w/a: read, write, append.
+: indicates allowing different forms of access, "r+" read/write, "w+" write, but also allow reading.
t/b: controls whether the file is opened in text or binary mode.
This may effect the os's treatment of things like newlines or behavior of seek (possible eventually: text mode may also handle UTF-8 and UTF-16 encoded files, which in binary mode would be treated as just normal bags of bytes).

File Methods
seek(offs, rel)
Seek within a file.

tell()
Tell current offset within file.

close()
Close file.

flush()
Force any output to disk/flush any input.

eof()
Indicate if at end of file.

inready()
Tells if more input is pending.

read_bytes(cnt[, offs])
Read bytes from file, returns a byte array.

write_bytes(bytes[, size[, offs]])
Write bytes to file.

read_value(typename[, offs])
Read a value from the file.

write_value(typename[, val[, offs]])
Write a value to the file.

read_string([size[, offs]])
Read a string from a file, possibly fixed-length.

write_strint(str[, size[, offs]])
Write a possibly fixed-length string to a file.

readln()
Read a line from the file.

println(...)
Print stuff and a newline to the file.

print(...)
Print stuff to the file.


Lists


Lists are a collection type made out of "cons cells".

<list>[<index>]        A particular index in a list.
<cons>.head/<cons>.h    The head for a cons cell.
<cons>.tail/<cons>.t    The tail for a cons cell.

<cons>.c((a|d)+)r
A certain trace through a list, where a is for head and d is for the tail.

Traditionally, these are also called car and cdr.

<list>+<list>    Concatencate 2 lists and return results.

List Methods

copy()
Copy list.

append(...)
Append lists and return the result.

nappend(...)
Destructively append lists and return result.

reverse()
Create and return a reversed copy of this list.

Destructively reverse this list and return the new base.


Strings


String Methods


length()
Get string length.

copy()
Duplicate a string.

tofloat()
Convert a string to its numerical value.

eatws([ws])
Eat whitespace from a string.

split([ls[, ws]])
Split a string.
'ls' gives chars that work as field seperators.
'ws' gives chars that are treated as "whitespace".
The field seperator chars, when encountered, will break parsing of the token.
Whitespace chars are those that are eaten prior to parsing a token.
Natually, both fields are set to be whitespace, causing the token to break when whitespace is encountered and eating whitespace prior to reading the token.

String Operators


a+b        Add String String    => New string with combined contents
a+b        Add String Integer => String with b added to the base
a-b        Sub String Integer => String with b subtracted from the base

a&b        Concatenate Strings/Concatenate a string with the textual representation of an object.

a<<b        Relative String Less Than
a>>b        Realtive String Greater Than
a<<==b    Relative String Less Than or Equal
a>>==b    Relative String Greater Than or Equal
    These compare strings by relative base, and are undefined for the case when a and b are different strings.

|a        String Length


Concurrency

Threads

Threads for the time being are implemented in software only (eg: non-os threads).

makethread(self, func)
Create a new thread using self as the toplevel and calling func.

builtin_sleep(time)
Internal function, try to sleep a given amount of time (may sleep less or do nothing).

thread <BLOCK>
Execute block in a new thread.


Pools

Pools are intended as a means of communication between threads, working as a kind of lifo buffer.

pool()
Creates a new pool.

<pool>(<value>)
Adds value into the pool.

join(<pool>)
Pull a value from a pool, waits until one is present.