
                                 Mats 2.42

                                    --

                             The AGI Compiler


---------------------------------------------------------------------


0. INDEX

    1. About Mats
    2. Mats Arguments
    3. Version History
    4. Source Syntax
      4.1. Defines
      4.2. Messages
      4.3. Comments
      4.4. Strings
      4.5. Variables
      4.6. IF statement
      4.7. Labels
    5. Thanks


---------------------------------------------------------------------


1. ABOUT MATS

    Mats is an AGI Compiler. I've tried to keep it simple, and
    it is. It's a dumb compiler.

    If you want to crash it, it will crash. Use to long strings,
    to many labels, or any overflows at all. There's no checks at
    all. If the user wants to crash the compiler, the compiler
    should crash.

    But if you use it to compile correct code, I hope and believe
    there will be no problems at all. If there is, that's a bug,
    and I would love to hear about it!

    The syntax is chosen to be as close to C as possible, with
    the main goal that the output from Showlog by Lance Ewing
    should compile without errors.

    Some additions have been made to make Mats more compatible
    with the other AGI compiler out there, AGIC.


---------------------------------------------------------------------


2. MATS ARGUMENTS

    Mats takes 4 optional arguments:

    -w <filename>   read words from <filename> instead of "words.tok"
    -o <filename>   read objects from <filename> instead of "object"
    -v <number>     if this option is used, the output file will have
                    an AGI header, with the selected number in it.
                    If not, the output file won't have a header.


---------------------------------------------------------------------


3. VERSION HISTORY

    2.42 * #message didn't work in last release

    2.4  * New preprocessor command: #include
         * Defines can be more than one word
         * Defines can't be used before they're defined

    2.3  * The v4++ commands weren't working.
         * The v4 = *v4 commands weren't working.
         * Divisions weren't working.
         * New precompile command: #message
         * Removed the Stringcatcher. I never liked it.
         * The has() statemant now reads everything inside the
           parenthesis as an absolute string. I don't know how
           this will be done in the future, but this works quite
           fine with the output from Showlog, as long as there are
           no objects with unbalanced parenthesis in their names.
         * Misspelling of center.pos is no longer supported.

    2.2  * Syntax checking in the IF statements.

    2.1  * Allowed another syntax to Goto: Goto(Label);
         * Mats should no longer require a Return(); statement at the
           end of each logic.
         * The center.pos test-command was earlier misspelled, but is
           now corrected. The old spelling is still supported.

    2    * Changed the name to Mats, as there are other AGI compilers
           out there.
         * Added C/C++ type comments.
         * Skipped the pre-compiler (no more temporary files).
         * Added defines.
         * Some kind of bug fixed. =)
         * If no vol-number is given, there will be no header in the
           output.

    1.0  * First release


---------------------------------------------------------------------


4. SOURCE SYNTAX

  4.1. DEFINES

    Defines are written like this:

      #define ego 0

    And all "ego" found will be replaced by a zero. This is a way
    of giving flags and variables names.

    It's possible to define whole statements:

      #define notyet print("Not yet!");



  4.2. MESSAGES

    Messages are written like this:

      #message 4 "Hello!"

    When messages are used in the source, such as Print("Hello!");
    the compiler will search through the messages and look for exact
    matches. If there is, the compiler will use the defined message
    number. If there isn't, a new string will be made.

    This means you'll have to change the messages in two places if
    you are to change them, and don't want loads of unused messages
    in the output logic. 


  4.3. COMMENTS

    Comments supported are:

      // the rest of the line

      [ the rest of the line

      /* until */

    The /* */ comments are nested. Look at these examples:

      /* comment start
        print("Hello");    // won't be run
        /*                 // a new comment start (will be ignored!)
          v32 = 15;        // won't be run
        */                 // uncomments the most inner comment
        print("Hey!");     // won't be run, still inside comments
      */                   // uncomments



  4.4. STRINGS

    Some special characters are supported by Mats. Those are:

      \n = New line
      \" = Quotation
      \\ = The \ character

    for example:

      print("\"Hello\"\n\nWorld!");

    Long strings can be devided up on several lines:

      print("This is a very, "
            "very long string!");



  4.5. VARIABLES

    Variables can't have real names, they must be called v42, where
    42 is the number of the variable. The v has to be in lower case.

    These are the supported operations:

      v3++;                // increase()
      v3--;                // decrease()
      v3 = v4;             // assignv()
      v3 = 4;              // assignn()
      v3 = v3 + 4;         // addn()
      v3 = v3 + v4;        // addv()
      v3 += 4;             // addn()
      v3 += v4;            // addv()
      v3 = v3 - 4;         // subn()
      v3 = v3 - v4;        // subv()
      v3 -= 4;             // subn()
      v3 -= v4;            // subv()
      v3 = v3 * 4;         // mul.n()
      v3 = v3 * v4;        // mul.v()
      v3 *= 4;             // mul.n()
      v3 *= v4;            // mul.v()
      v3 = v3 / 4;         // div.n()
      v3 = v3 / v4;        // div.v()
      v3 /= 4;             // div.n()
      v3 /= v4;            // div.v()
      *v3 = 3;             // lindirectn()
      *v3 = v4;            // lindirectv()
      v3 = *v4;            // rindirect()

    If you feel like writing "addn(v4, 4);" instead of "v4 += 4;" or
    "v4 = v4 + 4;", that's fine too.


    The increase and decrease functions (v32++ & v32--) must be on a
    separate, single line. This is NOT legal:

      if(v32++ == 3) {         // NOT legal
        ...
      }


  4.6. IF STATEMENT

    All if statments MUST be followed by an {. Even if there's only one
    line to execute. No ; is allowed after the braces.

      if(v32 == 4) {
        v32 = 5;
      }

      if(((v52 > v2) && (isset(50)) || isset(23)) {
        ...
      }

    Variable comparations supported are:

    v3 > 4
    v3 > v4
    v3 == 4
    v3 == v4
    v3 < 4
    v3 < v4
    v3 != 4
    v3 != v4
    v3 >= 4
    v3 >= v4
    v3 <= 4
    v3 <= v4

    Tests if v53 is not equal to v32 are done like this:

      if(!(v53 == 32)) {
        print("v53 isn't 32");
      }

    There are two special test commands, has() and said(). The syntax is:

      if(said(open, door)) {
        print("Ok!");
      }

    The number of arguments can vary. No quotations around the words.
    The words must be in the words.tok file.

      if(has(breath spray)) {
        print("Hey!");
      }

    No quotations here eighter.

    Else is supported:

      if(has(breath spray)) {
        print("You use the breath spray");
      } else {
        print("You haven't got it");
      }




  4.7. LABELS


    Labels are supported. Labels look like this:


      Label0:

    They must end with an ":", but can be called whatever you feel like.

      Start:

    Is perfectly legal. To goto a label you use the GOTO function:

      goto Start;

    Or the other syntax:

      goto(Start);

    


---------------------------------------------------------------------


5. THANKS

    Thanks to you for reading this file.
    Thanks to Lance Ewing for Showlog and documentation.
    Thanks to Joakim Mller for the tip about #define.
    Thanks to Peter Kelly for reporting bugs.
    Thanks to Floating Hills Software for their AGIC, and
      with that some competition.


/ Martin Tillenius (mrtn@rocketmail.com) (UIN: 1207958)
