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.