Boron User Manual

Version: 0.2.2
Date: 2011-11-23

Contents

1   Overview

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.

1.1   About This Document

This manual is largely incomplete.

There is a separate function reference and code documentation available online at http://urlan.sourceforge.net/boron.

2   Scripts

Scripts are UTF-8 encoded text files.

2.1   Comments

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
*/

2.2   Shell Invocation

The first line of a script may be a UNIX shell sha-bang (#!) command.

#!/usr/bin/boron

2.3   Command Line Usage

Usage:

boron [options] [script] [arguments]

2.3.1   Command Line Options

-e "exp" Evaluate expression
-h Show help and exit
-s Disable security

2.3.2   Command Line Arguments

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"]

3   Datatypes

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!  

3.1   Unset!

Unset is used to indicate that a word has not been assigned a value.

3.2   Datatype!

A value which represents a type.

3.3   None!

A value used to denote nothing.

3.4   Logic!

A boolean value of true or false.

3.5   Char!

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)'

3.6   Int!

Integers can be specified in decimal, or if prefixed with '0x', as hexadecimal.

Example integers:

24
0x1e

3.7   Decimal!

A floating point number.

Example decimal values:

-3.5685
24.

3.8   Coord!

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

3.9   Vec3!

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

3.10   Word!

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
>

3.11   Lit-word!

A literal word evaluates to a word! value.

3.12   Set-word!

Used to assign a value to a word.

)> a: 42
== 42
)> a
== 42

3.13   Get-word!

Used to get the value of a word without evaluating it.

3.14   Binary!

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}

3.15   String!

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^/"

3.16   File!

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

3.17   Vector!

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.

3.18   Block!

A block is a series of values within brackets.

[1 one "one"]

3.19   Paren!

Similar to a block, but automatically evaluated.

3.20   Path!

Example paths:

object/entries/1

3.21   Context!

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]

3.22   Func!

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!
][
    ; ...
]

3.23   Port!

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.

3.23.1   Standard IO Ports

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
]

3.23.2   Network Ports

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