  Help file for MK-Compiler V1.03 04/2014
  ---------------------------------------

  CONTACT
  -------

Author : guillaume.tello@orange.fr (write in french or english or spanish)
WEB    : http://gtello.pagesperso-orange.fr/

This program was written using PureBasic 4.41. It is freeware.
I'll be pleased to receive MK programs written with my compiler
and include them in my WEB page.

Thanks to:
   Eugene Troitskiy for corrections and cool ideas.

  BASIC OPERATIONS
  ----------------

First of all, the compiler is not case sensitive, so FRAC, or Frac or fRaC
are all the same.

To key in a number, use 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 and '.'
Sign change can be written as CHS or /-/
The exponent starts with EE.

Example for -4.2*10^6:  4 . 2 CHS EE 6
-> Compiler facility: you can use the '$' prefix : $-4.2e6
and let the compiler do it for yourself.
(note that in this case, only one 'e' for exponent)

Operations are +, -, /, *, ENTER, CX, LASTX, X<>Y (exchange) and ROT (rotate)
               INT (or [X]), FRAC (or {X}), ABS (or |X|), SGN (sign of a number), MAX
               >HM, HM>, >HMS, HMS>, RND (random generator).

               Known bug in MAX: if X or Y is nul, then MAX returns zero.

Algebraic functions: SQR (for square root), 1/x, x (or x^2), x^y.
Scientific functions are: SIN, COS, TAN (or TG), ARCSIN, ARCCOS, ARCTAN (or ARCTG)
                          EXP (or E^X), LOG, LN, PI, 10^X

Binary functions are: AND, OR, XOR, NOT.


  REGISTER USE
  ------------

A register can be one of the fifteen registers from 0 to 9 and a to e.
Store/Recall is done with STO and RCL.

STO 1 : store X into register 1.
RCL e : push register e on stack.

Values from 10 to 14 can replace registers from a to e.
RCL 10 is the same as RCL a, and STO (14) is the same as STO (e).

Indirect addressing is done with ()

STO (1) : store X into register pointed by R1.
RCL (e) : push on stack the register pointed by Re.
   Note that every time an indirect addressing is used with registers 0-3
   then the register is automatically decremented.
   The same when an indirect addressing is used with registers 4-6
   then the register is automatically incremented.

-> Compiler facility: you can rename a standard register with the following directive:

#reg r name

Example: #reg 5 count, and then you can use RCL count, STO (count), etc...

-> Compiler facility: =r is a short form for STO r
                      @r is a short form for RCL r

Example, instead of : RCL rate RCL dollar * STO euro
         you can use: @rate @dollar * =euro

This still works with indirect addressing: =(index) is the same as STO (index)
   store X into register pointed by index.

  BASIC PROGRAMMING
  -----------------

Some instruction require an address to jump to. You can go on using absolute
addresses (from 0 to 104), but it's easier to define labels and let the compiler
calculate the addresses for you.

A label is defined with a name followed by a ':', its value is the current
step pointer.

Loops are L0, L1, L2 and L3.
    L0 label or L0 addr

Unconditional jumps are GOTO, GOSUB and RTN
    GOTO label, GOTO addr or even GOTO (r) for indirect addressing.
    The same for GOSUB.
    RTN returns from a GOSUB call.

Conditional jumps are x=0, x<0, x>=0, x<>0.
    x=0 label, x=0 addr, x=0 (r) for indirect addressing.
    The same for the other tests.
    Remember that the jump is only taken if the test is false!

You can halt the program with R/S (or STOP or INPUT according to the best meaning for you).

NOP can be used to fill a space, 'no operation'.

Example :

$20 =0 =1
2
here:
   SQR
L0 here

there:
   X^2
L1 there

STOP

This will be compiled as:
2 0 STO 0 STO 1
2 SQR L0 05 X^2 L1 08 R/S

  ADVANCED PROGRAMMING
  --------------------

The compiler offers many loops and structures to ease programming
and source reading.

Comments are really useful to help reading a code.
A comment starts with the ';' character, from this point the line is ignored.

In the following, 'test' stands for one of the four tests available:
   x=0, x<0, x>=0, x<>0.

REPEAT ... UNTIL(test)
   repeat enclosed instructions until test is true.

FOR r ... NEXT
   repeat the instructions according to the value of register r.
   This register must be 0, 1, 2 or 3.

FOR r ... WHILE(test) ... NEXT
   the same as before, but the loop goes on as long as the test is true.

DO ... LOOP
   infinite loop.

DO ... WHILE(test) ... LOOP
   the loop goes on as long as the test is true.

IF(test)GOTO label (or addr or (r) indirect register)
   jump to label/addr if test is true.
   note that in the listing, you'll find the reciprocal test.

IF(test)THEN ... ENDIF
   if test is true, then execute instructions enclosed by THEN/ENDIF
   else, jump after ENDIF.

IF(test)THEN ... ELSE ... ENDIF
   if test is true, then execute instructions enclosed by THEN/ELSE
   else, jump to instructions enclosed by ELSE/ENDIF.

SUM r or SUM (r)
   replaced by sequence: RCL r + STO r
   the same if indirect addressing.(**)

MUL r or MUL (r)
   replaced by sequence: RCL r * STO r
   the same if indirect addressing.(**)

(**) with indirect addressing and registers 0 to 6, this will lead to an
error as the register is decremented/incremented when used.

  ERROR MESSAGES
  --------------

When the compiler reports an error, it precises the line containing the error.
According to your text editor, line numbers can start at 0 or 1. Default is 1.
If you want to change this, use this directive:

#base n (n being any number)

  COMPILE FOR EMULATOR USE
  ------------------------

This compiler can output a *.C3 file that can be loaded into the very good
emulator : Calculators 3000. To manage this, just use this directive :

#C3 n

n=0, no output (default value)
n=1, ask for saving the file when compilation is successfull.
n=2, auto save with same file name and C3 extension.

  Calling MK-COMPILER as a SLAVE program
  --------------------------------------

call : mk-compiler myfile.inf

One parameter is the info file, it is a text file that contains those lines:

path+name of source
path+name of dest
command number
path+name of C3

-> if command = 2
   compile source file to dest and eventually to C3 file.
   if a C3 file is present, then acts as if '#C3 2' was in the source.
   (note: in Slave mode, the #C3 directive is ignored)

-> if command = 7
   extract program from C3 file to source (dest is ignored)

-> if command = 8
   C3 is not a file name but a string with HEX codes
   convert those codes to a source (dest is ignored)

-> Upon return, you get a code : 
   00 : Ok, operation successfull
   01 : Can't read INF file
   02 : Unknown command in INF file
   03 : Can't open C3 file (with command 7)
   04 : Program not found in C3 file (command 7)
   05 : Bad HEX code string lenght (odd or null)
   06 : Bad HEX code in string
   07 : Can't create TXT file (command 7 or 8)
   08 : Can't open source (command 2)
   09 : Can't open destination (command 2)
   10 : Compilation error: low byte=10 and then error/256 = line number of error
        A message box opens with a compilation error giving more informations.




  -- END OF FILE --
