v0.01b, 23-Jun-1999
                                                           _____
                                                             / /
                SockZ - Stack Oriented Calculus Kernel in   / /
                  / /
                                                           
                      by Alain Brobecker (baah/Arm's Tech)
                     


  SockZ is a small programming language based upon the stack concept (smells
like Forth, isn't it?) and able to work with big relative integers. It features
only a minimalist set of instructions, but gives ability to create many more,
for example you can work with fractions at very little expense. This version of
SockZ is interpreted, but a compiler *might* come later on.

  SockZ stinks (ooops, does this mean that Forth does too?) and you shall not
expect much from its (mis)use. It was mainly written because i wanted a tool
to handle large numbers, i had a funny (i hope you like it) name for it and
it would be a weird entry in the CodeCraft 4Kb contest. ;)


          Contents ---->-->->> 1. Legalities
                               2. SockZ usage
                               3. Writing ZCode
                                  1. General Considerations
                                  2. Functions and Labels
                                  3. Stack Handling Instructions
                                  4. Arithmetic Instructions
                                  5. Output Handling Instructions
                                  6. Flow Control Instructions
                               4. ThanX and greetings
                               5. Future
                               6. History



------------------------------>  1. Legalities  <-------------------------------

  * You can freely copy this software as long as you leave files unaltered,
    and don't use it for commercial profit (pdl shall contact me first).
  * Please note that you use it (or not ;) at your own risks! (maybe i shall
    mention i do use it at my own risks ;)
  * Commented sourcecode is provided for inspiration to all coders out there.
    Usage of parts of code or ideas is encouraged as long as you credit me and
    your product is freeware.



------------------------------>  2. SockZ Usage  <------------------------------

  If you just click on it, it will just execute the ZCode (that's a program
written in the SockZ language) which is hardcoded in the executable, a simple
one computing all factorials until the memory explodes... ;)
  This feature is provided because the CodeCraft contest stated the programs
must be standalone, so the SockZ interpreter had to do something on its own.
  
  SockZ is controlled from the CLI, and i strongly recommand to use it from a
TaskWindow, unless you need maximum speed. The syntax is "SockZ FileName xxx"
or "SockZ xxx FileName", where FileName is the name of the ZCode file and xxx
is the amount of memory (in Kb) you want SockZ to use.

  Please note that FileName MUST not start with a digit (0 to 9 that is) since
to keep things simple i used the first digit to check wether i have to load a
file or to change memory amount. You can also use "SockZ File1 File2 xxx1 xxx2"
and in such case File2 will be executed with xxx2 Kb of memory.



----------------------------->  3. Writing ZCode  <-----------------------------

  This will be very short at the moment. I won't tell here what a stack or a
function are, but merely give a list of features and instructions. Watching at
the examples provided shall be handy, they are fully commented.
  When a stack is represented, like with .. C B A, the rightmost elt is the top
of stack, and the leftmost is the bottom.
  Instructions preceded by !!! are not yet available, and the ones by ???
may disappear in a future version.


1.General Considerations
~~~~~~~~~~~~~~~~~~~~~~~~
 * Instructions separators are space and the line separator (LF)
 * Everything is case sensitive
 * Numbers can be any integer in [-2^(2^34)+1;2^(2^34)-1]
   (since a number can use 2^29 longs, ie 32*2^29=2^34 bits)
 * The ZStack may not contain more than 2^31-1 elts
 * The comments are instrctions starting with a ; (as in assembly) and they
   finish with LF.
  

2.Functions and Labels
~~~~~~~~~~~~~~~~~~~~~~
  #FunctionName         Defines a function (shall exit with END)
  .LabelName            Defines a label

  FunctionName          Executes function (returns when END is encountered)
  LabelName             Jump to the label 

 * You must have at least one space or LF before and after label and function
   definitions, ie you must consider them as instructions.
 * You can give the same name to different functions/labels, but this is the
   last one which will be used.
 * The Functions and Labels shall not start with a number or a :. But they
   can contain those later (eg #copy2 is valid while #2copy and #:copy aren't).
 * You can make recursive functions, cross recursivity and whatever you want
   without asking yourself questions about precedence or the like.
 * The order in which you set the functions has no influence on speed.


3.Stack Handling Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 12345      .. C B A          -->  .. C B A 12345
 -6789      .. C B A          -->  .. C B A -6789
 COPY       .. C B A          -->  .. C B A A
 COPY2      .. C B A          -->  .. C B A B A
 DROP       .. C B A          -->  .. C B
 DROP2      .. C B A          -->  .. C
 SWAP       .. eN .. e2 e1 N  -->  .. e1 .. e2 eN
 SWAP2      .. C B A          -->  .. C A B
 SIZE       eN .. e0          -->  eN .. e0 N+1                 (size of stack)
 TIME       .. C B A          -->  .. C B A TIME       (32 bits internal clock)

 * -0 is not a valid number, neither are -00 or even -01. But you can use them
   as labels.
 * The top of stack is elt 0.
 * All possible permutations are generated by (1;n) transpositions, this
   explains why SWAP is the only displacement instruction.
 * COPY2 is the same as COPY 3 SWAP COPY 4 SWAP
 * DROP2 is the same as DROP DROP
 * SWAP2 is the same as 2 SWAP


4.Arithmetic Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~
 +          .. C B A    -->  .. C A+B
 -          .. C B A    -->  .. C B-A
 *          .. C B A    -->  .. C A*B
!!! /          .. C B A    -->  .. C B/A B%A

 * The division is not yet available.


5.Output Handling Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 CR         New line
??? HPRINT     Remove and prints the top of stack in hexadecimal
!!! INPUT      Remove and prints the top of stack in hexadecimal
!!! PRINT      Ask for a decimal number an put it on stack
 "SockZ"    Prints the string "SockZ" on screen
??? "RuleZ+LF  Prints the string "RuleZ" on screen

 * INPUT and PRINT are not yet available. It will be possible to emulate it as
   soon as the division is implemented though.
 * Note carefully that HPRINT/PRINT removes the top of stack.
 * HPRINT may disappear.
 * Use "" to put a " in a string (same as BASIC).


6.Flow Control Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~
 SKIP=0     .. C B A    -->  .. C B    ;If A=0 then skip next instruction
 SKIP<>0    .. C B A    -->  .. C B    ;   A<>0
 SKIP>0     .. C B A    -->  .. C B    ;   A>0
 SKIP<0     .. C B A    -->  .. C B    ;   A<0
 SKIP>=0    .. C B A    -->  .. C B    ;   A>=0
 SKIP<=0    .. C B A    -->  .. C B    ;   A<=0
 SKIP=      .. C B A    -->  .. C      ;If B=A then skip next instruction
 SKIP<>     .. C B A    -->  .. C      ;   B<>A
 SKIP>      .. C B A    -->  .. C      ;   B>A
 SKIP<      .. C B A    -->  .. C      ;   B<A
 SKIP>=     .. C B A    -->  .. C      ;   B>=A
 SKIP<=     .. C B A    -->  .. C      ;   B<=A
 END        Return from current function or end the program

 * SKIPs instructions remove the parameters they use. If it were not the case
   and the elts were no more needed after the SKIP, we would possibly need to
   use two DROPs or DROP2s, and they would be at different places, which sounds
   far worse.
 * Also look at the paragraph on Functions and Labels for more flow control.



-------------------------->  4. ThanX and greetings  <--------------------------

  I would like to thank the following people for the precious help they gave
during the conception of this language and the interpreter:

 * Frederic Elisei (aka ArmOric/Arm's Tech), who gave loads of help (teaching
   me ARM assembly and how the flags works... ;),  and interesting comments
   concerning algorithms used in language creation (not used here). As soon as
   i spoke about SockZ, he suggested to make a compiled/tokenised version.
  
 * Vincent Lefevre, for precious help concerning computationnal algorithms,
   and for providing comments and sourcecode of his ArmPi programs (available
   on his Web Page). If ever you have a question dealing with mathematics,
   no doubt Vincent will be able to give you an answer.

  Also thanks to all friends, demo coders, CodeCraft supporters and everybody
at the ML ArmADA for support and nice chats in general. Sorry, but you are too
numerous to count, and i have no pre-made list to forget noone. Maybe in another
version of this doc ;).
  
  

--------------------------------->  5. Future  <--------------------------------

  Depends on the feedback i receive. But at first i'll have to finish this
interpreted version of SockZ before considering to modify the language and add
new (and usefull) features. I would be glad to receive any comments, and to see
what usage you make of SockZ. Here follows all the things one can dream of:

 * Optimised SWAP2 (i know how to do it, so that's easy).
 * A Compiler/Tokenised version (that shall not be that hard).
 * Better error handling, showing line numbers etc...
 * An include pseudo instruction for easy use of libraries.
 * LOAD/SAVE part of the stack. Sounds a bit annoying since one parameter for
   loading/saving is a name, and i have no string support.
 * String support?
 * Even more data structures, binary objects and adresses to access memory?
   Also BINLOAD/BINSAVE instructions?
 * More algorithms for fast computation of multiplication and division when
   numbers are getting BIG (Karatsuba, Fourier for mul? Newton for div?).
 * Support for hexadecimal numbers (&1234, ASL, ASR, LOG2)?
 * An OVER instruction to copy Nth elt on top of stack? OVER2 too.



-------------------------------->  6. History  <--------------------------------

1999jun23 -- Wiped bug in SKIP=0, modified HPRINT, tidied ZCode examples.
1999jun22 -- Numerous bugs eradicated in multiplication, which was rewritten.
1999jun20 -- Multiplication implemented, but there's a bug which caused 3
             machine crashes and not yet found.
1999jun19 -- Corrected a nasty bug in instruction identification.
1999jun18 -- HPRINT, stand alone environment (no more Basic+BasDebug).
1999jun13 -- TIME.
1999jun12 -- SWAP, SWAP2 (uses SWAP at the moment).
1999jun11 -- DROP2, removed small bugs in SKIPs.
1999jun10 -- SKIP instructions modified (now monoadic & diadic versions).
             From now on 0 is considered as a positive number only.
1999jun09 -- COPY2, number checking is now made during prepass.
1999jun07 -- Substraction of Znumbers with same sign (or addition with
             different signs).
1999jun06 -- All remaining SKIP instructions, addition of Znumbers with same
             sign (or substraction with different signs).
1999jun04 -- SKIP= and SKIP<>.
1999may30 -- COPY,DROP,SIZE,END and function/label handling.
1999may29 -- Implemented NumberToStack conversion routine.
1999may27 -- Removed small bugs in the instruction decoding.
1999may14 -- Added memory error handling in function/label creation.
             Coded the instruction decoding (not tested yet).
1999may12 -- PrePass rewritten.
1999may11 -- PrePass code now seemingly working.
1999may09 -- Gentlemens start you engines.
...       -- Zzzzzz ;)
1997dec?? -- First dated sources, hash table creation in Basic.
