RE: RE. basic frontend / sdcc

Introduction to avBas:

avBas is a frontend compiler for a Basic-like language that uses 
standard C compiler as backend. That means that avBas is theoreful
more portable and more optimizable for microcontrollers because,
only a subset of C is used.

In addition to the simplicity of Basic, avBas offers you full 
access to the power of C and in special to existing or new 
C libraries. 

Differences from Basic 
There are a few differences between avBas and traditional Basic 
that you should be aware of: 

     ·  All variables must be declared with Dim  and variable
        declaration must occur befor any statement.
        Example: Dim x as word 
	         Dim val Array(10) as Byte ` creates val[0] - val[9]

     ·  Comments at the end of a line start with ` (a back quote) 
        instead of an ordinary quote 
        Example: x=f() ` Set x to the current value 
	NOTE: ordinary quote as comment is possible when the 
		line begins with a comment

     ·  Arrays use square brackets for indices:  
        Example: sample[i]=getValue() 

     ·  Calling a subroutine or a function with no arguments still 
        requires empty parenthesis 
        Example: x=f() 

     .  Subroutines/functions, labels and variables, all tree have
        a separate namespace.
	variables are converted to uppercase, 
	subroutines/functions to lowercase,
	and labels become the prefix lbl_ .

     ·  Functions return a value via the RETURN statement 
        Example: RETURN 10 
 
     ·  You must avoid using words reserved by your C compiler 
          as identifiers even if they are legal Basic identifiers 
          Example: break=10  ` this is legal, 
	           break:  motor = off ` this is legal
          function break ()  ` break is reserved by C compiler! 
	  This limitation apply only to sub/function definitions

     ·  Parameters are passed to functions and subroutines by 
          value, not by reference (that is, functions and subroutines 
          receive copies of their arguments by default) 
	NOTE: in future parameter could have the form:
	    foo ( bar is footype , ...) instead of the c type ( footype bar).
	    In this case, a 'by' 'reference' could be added to change the value
	    passing. Otherwise C convention apply.
	NOTE: check for special handling for redundand procedures when using
	    fixed parameter overloading like sdcc

     ·  There is a GOSUB statement, but avBas uses named 
          functions with formal parameters.
	  Function calls uses the HW stack, the gosub statement
	  uses a software stack and requires some support files.
	  See the manual for the differences, limitations and suggestions.

     ·  avBas uses C-language operators, most of which are the 
          same as their Basic equivalents; a few are different (for 
          example Basic's MOD operator is % in avBas) 
	  NOTE: the standard include file have some #defines for aliasing
	  mod/and/or/xor ... to % & | ^
	  NOTE: after adding a symbol table, this can change in favor of
	       	automatic detecting the usage for logical or binary operators.
	  
	  The basic operators = and <> are full recognized by avBas
	  and are not valid inside assignment (let) statements.

     ·  avBas don't uses basic type convention for the numeric basesytem.
          traditional basic: $Ab for hex,  %01001 for binary, 123 for decimal
	  avBas: 0xab for hex, 0b01001 for binary, 123 for decimal following
	  the C standard.

@                ASM Pass through
@@               C   Pass through
#Asm		 Multiline ASM Pass throught
#EndAsm		 Multiline ASM Pass throught
#C		 Multiline C   Pass throught
#EndC		 Multiline C   Pass throught
#include         C   include 
#Link            Add file to compile              additionally scan for symbols 
#....		 everything that don't is #link, #asm/#endasm/#c/#endc/#basic
                 is passed to the C compiler
$....		 The dollar is exchanged with a hash '#' , see the description
		 for that. This is to have a compatibilitay with some basics
		 that uses $if $endif $define and $basic (pragma like).
'                Comment at start of line 
`                Comment at end or start of line 
Asm		 Multiline ASM Pass throught
EndAsm		 Multiline ASM Pass throught
Call		 Calls a sub/function in the basic usual style
Const            Define constant 
Define           Define type  or alias
		 Example: Define sword As signed short  ` type definition
		          Define led   IS pb3           ` alias definition
Dim              Declare variable 
		 Example: Dim count  ` count is int type 
		          Dim arr ARRAY(4), count, tmp as unsigned int , 
			  w,t as word
Do/Loop          Execute code repeatedly 
		 Do  ` loop forever
		    ...
		 loop
		 Do   while/until  <cond>   => same as while (<cond>) {...} ...
		    ...
		 Loop
		 do
		    ...
		 Loop   while/until  <cond>   => same as do { ...} while (<cond>);
End              Stop program or end subroutine/function 
		 End if
		                                          End loop
		 End sub
		 End function
		 End              (inside function) =>  while(1);
		 End		  (outside function) => terminate avBas parser
For/Next         Execute code repeatedly 
		 For i = foo to bar 
		 For i = foo to bar step foobar
Function         Define a function 
		 Function foo(word bar) as foobar
		   ...
		 end function
Goto             Goto a label 
If/Then/Else     Conditionally execute code , two variants exists
		 IF <cond> Then <statement>
		 IF <cond> Then
		   ...
		 [ Else ]
		   ...
		 End If
Include          Include a file 
Let              Optional assignment keyword , can be omitted
Goto             Goto a label 
Rem              Remark 
Return           End a function or subroutine 
Sub              Define a subroutine, same as Function, no return value
Use		 Use a basic library (currently not implemented)

basic directives:
$basic dim <type>	Use <type> for dim statements without type definition.
$basic compat		Compatibility mode, insertes a special main prelude in
			the output file and a suffix after a eof is read.
			Advanced type procedures must be defined before this 
			directive. This apply to variables, that should be
			accessible from other files. This make it possible to
			use the keyword gosub and gives you 16 gosub levels
			in addition to the processor depended xx levels.
$basic gosub <level>	This specify the deep of the gosub levels , must
			be a power of 2 , depredicated, use define
   ----------- not implemented, only parsed and discarded ------------
$basic library		build a library that can be linked. Every procedure
			results in a single .o file that results in a library.
$basic command		build a command file, that can be used to extend the
			frontend.
$basic include		used inside command file to embedd a ordinary 
			file inside a command file.

NOTE: '#' and '$' are equivalent when it's the first nonspace on the line.