PERLSTONE-v1.0.txt

Perlstone Specification v1.0
(See http://wiki.sk89q.com/wiki/CraftBook/PerlStone for a up-to-date version,
 and examples)

Introduction
------------

Perlstone, named for Perl of which which is often compared to line noise, is a
small scripting language that can be used in CraftBook to program programmable
logic chips. The language was designed and the interpreter written by Lymia.

Features of Perlstone are:

    * A stack
    * A 32-cell persistent variable table (indexed with 0-9 and a-v)
    * A 32-cell temporary variable table (indexed with 0-9 and a-v)
    * A 32-cell local variable table (for functions, and indexed with 0-9 and
      a-v)
    * Three input registers 

A script is grouped into up to one hundred functions. Functions are strings
containing an arbitrary number of opcodes, and are separated by the character
':'. Functions are also indexed with numbers 0 though 99. Some functions may
take arguments (which are pushed onto the function's stack when it is called)
or return a single boolean value. When a function is called, a new function
local variable table is created, pre-filled with all 'false' values and used
for the duration of the function. 

Opcodes
-------

[opcode][operands] (stack arguments -> opcode return value) - description

Constant functions:
+ (->t) - pushes 'true' onto the stack
- (->t) - pushes 'false' onto the stack

Variable functions:
A (->a) - pushes contents the A input register onto the stack
B (->b) - pushes contents the B input register onto the stack
C (->c) - pushes contents the C input register onto the stack

Srn (v->) - pops the top value of the stack, and stores it to slot n in the
            table r (p for presistant, t for temp, l for local) 
Lrn (->v) - pushes the value n in the table r (defined as in the >rn opcode)
            onto the stack

Stack fuctions:
d (a->aa) - duplicates the top value of the stack
p (a->) - pops the top value of the stack, and discards it
vn (v(...)->v) - copies the value n values down in the stack onto the top

Logical functions:
! (a->r) - pops the top value of the stack, and pushes it's inverse
^ (ab->r) - pops the top two values of the stack, and pushes the xor of them
& (ab->r) - pops the top two values of the stack, and pushes the and of them
| (ab->r) - pops the top two values of the stack, and pushes the or of them
= (ab->r) - pops the top two values of the stack, and pushes their equality
.abcd (ef->r) - custom logic gate, pops the top two values of the stack (e and
                f) and if ef is 00, pushes a onto the stack, if ef is 01, 
                pushes b onto the stack, if ef is 10 pushes c onto the stack
                and if ef is 11 pushes d onto the stack.

Flow control functions:
cffn (123...->r?) - Pops n values off the stack and calls the function f
                    (referenced by a two-digit number) and pushes the
                    previously popped values onto the called function's stack,
                    and pushes the return value (if one exists) of the called
                    function onto the calling function's stack 
tffn (123...->r?) - calls the function defined by f with n arguments are in c,
                    pops the top value of the stack, and returns it.
[ (v->) - pops the top value of the stack, and if it is false, jump to the
          opcode after the corresponding ] opcode (as defined by a system of
          nested '[' and ']' instructions) 
] (v->) - pops the top value of the stack, and if it is true, jump to the
          opcode after the corresponding [ opcode (as defined in the [ opcode) 

s - returns from the current function
r (v->) - pops the top value of the stack, and pushes that value onto the stack
          of the calling function and returns from the current function

Planned Features
----------------

Version 2: Functional style programming, with changes including combinators,
           and other unlambda styled antics. (Effectively making the types
           boolean and function)