Shell documentation

index:

Presentation:

The shell is an interpreted stack based language similar to forth. (Datas are stored into a lifo stack)

The difference with forth are:

When executing an error is produced if:

Note:

Stack use:

ex 1

output: Hellow world

ex 2

output: Value = 100

ex 3

 

output: Value = 50

Variable definition:

To declare or set variable value, use char '!'

A new variable is declared and initialized at same time

To write to existing variable, use char '!'(same as declare)

To read a variable, use char '.'

Note: To make difference with  shell user functions (for readibility), variable name must not start with '_' char.

ex 4

 

output : Value = 100

Function call:

 A shell function is declared with char ':'

To call a shell function, use char '_' preceding function name.

ex 5 (function call without parameters)

  • Declare shell function "PrintHello" (that print "Hello")
  • in main, Call shell function "PrintHello"
  • Push string "World\n"
  • Call printf

output : Hello World

Function parameters:

Function parameters must be declared using '%' char + parameter type.

Function can return only one value on stack if 'return' keyword is used.

Actually, function parameters types can be:

  • '%i' for integer
  • '%s' for strings

note: The parameters type declaration must have same order than datas on stack

ex 6 (function call with parameters)

  • Define function Sub having 2 input parameters of type integer
  • Substract the 2 values on stack (must be done after '{' to respect rule: stack empty at end of line)  and return the result (pushed on stack)
  • Define function main
  • Push 10 & 20 on stack
  • Call shell function :Sub
  • Call printf

output : Result = -10

ex 7 (function call with named parameters)

To increase readibility, function parameters can be named. This must be done immediatly when entering in function bloc on the first line.

  • Define function SubPrint having 3 input parameters (2 integers and 1 string)
  • (in reverse stack order, as poped), name string parameter as 'Name', second stack parameter as 'b', first as 'a'
  • Do a - b (push result), push Name value, push constant string, call printf
  • Define main
  • Push 100 and 50 and string "Hello" and call shell function :SubPrint

output : Sub (Hello) = 80

Tests:

 keywords used for test are :

  • 'if' : applyed on { } bloc
  • 'else' : applyed on { } bloc
  • '?' can be applyed on keyword or function that do not require stack parameters (mainly for loop control, see Loops )

ex 8

output : a <= b

Loops:

keywords used for loops are:

  • 'loop' : define { } loop bloc
  • 'continue' : restart a loop (as C work)
  • 'break' : break a loop (as C work)

ex 9

  • Define variable i = 0
  • Define loop bloc
  • Increment i
  • Continue if (i > 2) && (i <= 8)
  • Print i
  • Break if i >= 10

output : 1, 2, 9, 10,

Command line execute:

Command line functions can be executed as if it was typed directly on keyboard.

Use keyword 'cmd'

ex 10

  • push string "printlog"
  • use string as command line using 'cmd' keyword
  • delete from stack the returned value (or can be used as success test)

This launch the command "printlog".

Because command line functions always return an integer value, to keep stack size = 0 at line end, the command returned value must be deleted (or can be used if required)

To delete the top stack value, use 'drop' command

Resume of keywords:

 Keywords:

  • if       // test
  • else    // test
  • return   // specify function return a value
  • loop     // define a loop
  • break    // break a loop
  • continue // continue a loop
  • drop     // delete a stack value
  • cmd      // launch a command
  • printf   // display a string

Operators:

  • :xxx    // shell declare function xxx
  • _xxx    // shell call function xxx
  • !xxx    // declare variable xxx (+ init with top stack value) or set variable xxx
  • .xxx    // read xxx variable (+ push on stack)
  • ?xxx    // conditional execute xxx (xxx must be function that require no stack parameters)
  • { }     // define code bloc
  • %i      // define function parameter as integer value (32 bits signed)
  • %s      // define function parameter as string pointer

Other operators same as C:

  • test:  ==, !=, >, >=, <, <=
  • increment/ decrement an integer variable: ++, --
  • logical: &&, ||
  • arithmetic: +, -, *, /, %
  • binary: ~, &, |, ^, <<, >>
  • special for unsigned numbers U>, U>=, U<, U<=  is same to >, >=, <, <=  but compare numbers as unsigned integer

To be done: Add readkey keyword

Aspect of a more complicated shell source (test code doing test only)