| Version: | 0.2.2 |
|---|---|
| Date: | 2011-11-23 |
Contents
Boron is an interpreted, prototype-based, scripting language.
Language features include:
- Garbage collected datatype system with prototype based objects.
- Written in C to work well as an embedded scripting language.
- Small (but not tiny) binary & run-time environment.
This manual is largely incomplete.
There is a separate function reference and code documentation available online at http://urlan.sourceforge.net/boron.
Scripts are UTF-8 encoded text files.
Single line comments begin with a semi-colon.
Block comments are the same as C block comments. They begin with '/*' and continue through '*/'. Unlike C, block comments can be nested.
Comment examples:
; line comment add 2 4 ; result is 6 /* Block comment */
The first line of a script may be a UNIX shell sha-bang (#!) command.
#!/usr/bin/boron
Usage:
boron [options] [script] [arguments]
| -e "exp" | Evaluate expression |
| -h | Show help and exit |
| -s | Disable security |
If the interpreter is invoked with a script then the args word will be set to either a block of strings, or none if no script arguments were given.
So this Boron command:
boron -e "probe args" file1 -p 2
Will print this:
["file1" "-p" "2"]
| Datatype | Examples |
|---|---|
| unset! | |
| datatype! | logic! int!/decimal! |
| none! | none |
| logic! | true false |
| word! | hello focal-len .s |
| lit-word! | 'hello 'focal-len '.s |
| set-word! | hello: focal-len: .s: |
| get-word! | :hello :focal-len :.s |
| char! | 'a' '^-' '^(01f3)' |
| int! | 1 455 -22 |
| decimal! | 3.05 -4. |
| coord! | 0,255,100 -1, 0, 0 |
| vec3! | 0.0,255.0,100.0 -1.0, 0, 0 |
| string! | "hello" {hello} |
| file! | %main.c %"/mnt/Project Backup/" |
| binary! | #{01afed} #{00 33 ff a0} |
| time! | 10:02 -0:0:32.08 |
| vector! | #[1 2 3] #[-85.33 2 44.8] |
| block! | [] [a b c] |
| paren! | () (a b c) |
| path! | obj/x my-block/2 |
| lit-path! | 'obj/x 'my-block/2 |
| set-path! | obj/x: my-block/2: |
| context! | context [area: 4,5 color: red] |
| error! | |
| func! | inc2: func [n] [add n 2] |
| port! |
Unset is used to indicate that a word has not been assigned a value.
A value which represents a type.
A value used to denote nothing.
A boolean value of true or false.
A Unicode character. A char! can be specified with either a UTF-8 character between two single quotes, or an ASCII caret (^) sequence between two single quotes.
The following caret sequences can be used:
| Sequence | Character Value |
|---|---|
| ^- | Tab, 0x09 |
| ^/ | New line, 0x0A |
| ^^ | Caret, 0x5E |
| ^0 - ^F | Hexidecimal nibble, 0x00 - 0x0F |
| ^(xxxx) | Hexidecimal number, 0x0000 - 0xFFFF |
For example, a new line character could be declared in any of the following ways:
'^/' '^a' '^(0A)'
Integers can be specified in decimal, or if prefixed with '0x', as hexadecimal.
Example integers:
24 0x1e
Integer coordinate that is handy for specifying screen positions, rectangles, colors, etc.
A coord! can hold up to six 16-bit integers.
640,480 ; Screen size 45,10, 45,18 ; Rectangle 255,10,0 ; RGB triplet
Vec3 stores 3 floating point values.
A Vec3 is specified as two or three decimal numbers separated by commas. If none of the numbers has a decimal point then the value will be a coord!.
0.0, 1.0 ; Third component will be 0.0 1.0,0,100
A word is a series of ASCII characters which does not contain white space. The first character must not be a digit. All other characters may be alpha-numeric, mathematical symbols, or punctuation. Case is ignored in words.
Example words:
app_version _60kHz_flag MTP-3 >
A literal word evaluates to a word! value.
Used to get the value of a word without evaluating it.
A binary value references a series of bytes. Binary data is specified with hexadecimal values following a hash and opening brace (#{) and is terminated with a closing brace (}). White space is allowed and ignored inside the braces.
#{0000ff01}
#{0000ff01 0000f000
03ad4480 d17e0021}
)> to-binary "hello"
== #{68656C6C6F}
Strings are UTF-8 text enclosed with either double quotes or braces. The text can span multiple lines in the script when braces are used.
Strings can include the same caret character sequences as char! values.
String examples:
"Alpha Centari"
{This string
spans multiple lines.}
"First line^/Second line^/"
A file value is a string which names a file or directory on the local filesystem. They begin with a percent (%) character. If any spaces are present in the path then it must be enclosed in double quotes.
File examples:
%/tmp/dump.out %"../input files/test42" %C:\windows\system32.exe
Vectors hold a series of numbers using less memory than a block!.
All numbers in a vector are either 32-bit integers or floating point values. If the first number is specified as a decimal!, all numbers will be floating point.
Similar to a block, but automatically evaluated.
A context holds word/value pairs.
Example context:
entry: make context! [ name: "John" age: 44 job: 'farmer ]
Contexts can be created from existing ones. So given the previous entry context a new farmer could be created using make again.
joe: make entry [name: "Joe" age: 32]
The context word is normally used to make a new context instead of make context!:
unit: context [type: 'hybrid level: 2]
Functions can be defined with or without arguments. The return value of a function is the last evaluated expression.
The does word is used to create a function with no arguments.
hello: does [print "Hello World"]
Local functions values can be declared in the signature block. These locals are initialized to none.
; Here is a function with two arguments and one local variable.
my-function: func [arg1 arg2 | var1] [
; var1 is none.
; TODO: Write this function body.
]
Arguments can be limited to certain types by following the argument name with a datatype in the signature block.
func [
blk block!
count int!/decimal!
][
; ...
]
Ports are a general interface for various input/ouput devices.
The open and close functions create and destroy ports. The read and write functions are used to recieve and send data.
To use stdin, stdout, and stderr streams use open with the integer 0, 1, or 2.
To read commands from stdin:
t: open 0
cmd: ""
forever [
wait t
read/into t cmd
if eq? cmd "quit^/" [break]
print cmd
]
Here is a simple TCP server which sends clients a message:
s: open "tcp://:6044"
forever [
con: read wait s [
write con "Hello, client.^/"
close con
]
]
And the client:
s: open "tcp://localhost:6044" print to-string read s close s