------------------------------------------------------------------------ AA GGGG IIIIII CCCC AAAA GG GG II CC CC AA AA GG II CC AAAAAA GG GG II CC AA AA GG GG II CC CC AA AA GGGG IIIIII CCCC === ===== ======== ============= AGI LOGIC COMPILER DOCUMENTATION === ===== ======== ============= Floating Hills Software Version 1.42 ------------------------------------------------------------------------ WHAT IS AGIC? Until recently, there has been no easy way to recompile the logic code included with AGI games. This program, AGIC, is such a compiler. With it, one can compile a modified or new logic file, including the AGI Template Game. The major benefits of using AGIC include: * AGIC will compile complex expressions in if statements down to the simple form needed by the AGI interpreter. * AGIC includes error and limited type checking, making programming easier. * AGIC can easily be used with the included GNU C preprocessor. This allows one to use of #defines and #includes. AGIC and the associated utilities are free software. The source code for AGIC can be used in your own programs provided certain restriction are met. For information, read the COPYING file included with this distribution. Help support our planet by writing more software under the GNU Public License. CHANGES IN VERSION 1.42 OF AGIC? * The name centre.posn has been replaced with center.posn, the correct form. * Return() works. * Limited type checking for arguments of functions has been added. * The lexer symbol length bug has been fixed. * The C-style string \" \\ and \n are supported. * Error checking recovers nicely after errors. * More errors are now detected. * The #message command is now available. * Strings spanning more than one line are now supported. * Parenthesis around goto labels are now optional. * C-style indirection now works. * Symbols with confusing characters may be surrounded with |'s * The Template Game compiles as it should! WHERE IS THE LATEST VERSION OF AGIC? The latest version of AGIC and HTML-ized documents regarding it can be downloaded at http://krypton.mankato.msus.edu/~jimf/agic/agic.htm Questions regarding AGIC may be sent to greekcat@hotmail.com. ------------------------------------------------------------------------ === ======== THE COMPILER === ======== SECTION 1.1 - COMPILING A FILE To compile a file, use the command line AGIC filename [-o object_filename] [-t token_filename] [-e output_filename]. By default, AGIC will use OBJECT and WORDS.TOK for the object and token filenames, respectively. The output will normally go to LOGIC.OUT. To make life easier, this distribution includes various batch files for compiling with the preprocessor. SECTION 1.2 - EXECUTING COMPILED FILES To execute a logic file, one will need to glue the logic file and other resources back into volume and directory files. There are automated utilities to do this (i.e., AGIGlue or AGI Studio). SECTION 1.3 - ERRORS * C000 Warning: Unknown character - The compiler found a character in the source file that it did not know what to do with. It has been ignored. * C001 Error: Syntax error * C002 Error: Could not resolve label - The source file included a goto to a label not appearing in the source file. * C003 Error: Too many strings - The source file included more messages than AGI allows for. * C004 Error: String already used - A defstr or #message attempted to set a message index already used. * C005 Error: Could not resolve token - The compiler could not find the given token in the WORDS.TOK file. * C006 Error: Could not resolve object - The compiler could not find the given object name in the OBJECT file. * C007 Error: Could not resolve function - The compiler could not find a function with the given name in the AGI command list. * C008 Error: Unterminated string constant - A string was begun but did not end with a " before the end of the line. * C009 Fatal Error: Out of memory * C010 Error: Bad string control code - A string included a \ code besides \\, \n, or \". * C011 Error: Unterminated symbol - A symbol block was begun with | but was not terminated with another | before the end of the line. * C012 Warning: Bad type - A variable was passed to a function wanting a number or a number was passed to a function wanting a variable. * C013 Warning: Bad number of arguments - A function was passed too many or too few arguments. * C014 Warning: Conditionals should use ==, not = - A conditional used a = instead of the more correct ==. It has assumed that == was intended. ------------------------------------------------------------------------ ==== ======== AGIC LANGUAGE ==== ======== For the most part, the language is just like a mix of C and the output from the SHOWLOG program. The most important difference is the existence of a #message directive. SECTION 2.1 - VARIABLES All variables are referenced as a lower-case v followed by the variable index. For example, variable number 3 is simply v3. The included C-preprocessor can be used to name variables. SECTION 2.2 - FLAGS Flags can be referenced simply by the number (allowing the function to discern the difference) or by a lower-case f followed by the flag index. For example, flag 5 is simply f5. Flags are turned into numbers in the current version of AGIC. The included C-preprocessor can be used to name flags. SECTION 2.3 - FUNCTIONS Functions are called as in C, (i.e., foo(2,bob); or shakey(); ). AGIC now includes limited type checking. The only distinction, however, is made between variable and non-variable arguments. Thus, load.view.v(12) will cause a warning, but set(5) and set(f5) are equivalent. SECTION 2.4 - CONDITIONALS An if statement is the only branching command in AGIC. An if statement is as follows: if (expression) { logic } else // optional! { more logic } Although AGI, places strict limits on the complexity of boolean expressions, AGIC overcomes those limits by applying DeMorgan's laws to all boolean expressions until they are simplified down to a level applicable to direct machine code translation. Thus, the normal C logical operators (such as ! for not, && for and, and || for or) are legal in any combination one desires. The compiler will simplify the expression down to the appropriate level. SECTION 2.5 - GOTO AGIC also allows the programmer to use the GOTO command. To define a label, simply begin a line with the name of the label (without spaces) followed by a colon. To goto a label, use the syntax goto(labelname); or now goto labelname. Calling a labelname that is not defined until after the goto is perfectly acceptable. Although both parenthesis and parenthesisless forms of goto are acceptable, the parenthesis form is preferred. All other commands in AGI require parenthesis and goto should not be an exception. SECTION 2.6 - MESSAGES One can use a string as a parameter to any function by simply including that string, enclosed in quotes (", not '), as the parameter. The compiler will allocate a message table entry and store the string there. If one uses the same string again, the compiler will reference the old message table entry. Strings can include the usual \\, \n, and \" as used in C. They can also span multiple lines as they would in C. SECTION 2.6 - #MESSAGE AND DEFSTR Sometimes, it is necessary that a particular string be assigned a particular entry in the message table. To do this, one uses the #message command. #message stores the given string at the given message table entry. The #message directive is simply: #message num "string text goes here" For compatability, defstr is still supported. SECTION 2.7 - ARITHMETIC When using AGIC, it is not always necessary to call functions to perform most arithmetic operations. Rather, these operations can be performed individually on a line. In particular, AGIC supports the C operators =, +=, -=, *=, /=, ++, and -- between variables and integers. SECTION 2.8 - INDIRECTION AGIC also supports c-like indirection commands, in particular: v10 = *v22; // rindirect(v10,v22) *v10 = 22; // lindirectn(v10,22); *v10 = v22; // lindirectv(v10,v22); SECTION 2.9 - THE PREPROCESSOR This release of AGIC includes a Win32 port of the GNU C preprocessor. This can be used quite easily on AGI logic files, allowing variables to be defined and files to be included. The compiler is designed to deal with the modified output from the preprocessor. Comments and whatnot are also taken care of by the preprocessor. SECTION 2.10 - THE [ COMMENT Any text following a [ is considered to be a comment. SECTION 2.11 - SYMBOL BLOCKS At times, it is impossible to compile a logic file because it references some symbol which contains parenthesis or some other character which confuses the compiler. In those cases, the symbol may be surrounded with |'s. For example: if (has(|Buckazoid(s)|)) { ... } Symbol blocks are an unstandard feature of AGIC. ------------------------------------------------------------------------ === ====== ======= THE SAMPLE PROGRAM === ====== ======= The sample program has been removed beginning with AGIC v1.42. We suggest that you download the excellent Template Game. Since AGIC now compiles the template game, it is a far more interesting choice than a simple program which displays a picture. ------------------------------------------------------------------------