utils/mocha/README.md

   1 # mocha - A .script to .java translator
   2
   3 This utility uses the [PLY (Python Lex-Yacc)](http://www.dabeaz.com/ply/) library to generate .java files from .script file inputs. To install this library on debian based systems run the following command:
   4
   5     sudo apt-get install python-ply
   6
   7 # parse_expr.py - Parse debugging utility/example
   8
   9 This tool will parse any expression given to it and print out a string representation of the AST.
  10
  11     ./parse_expr.py 'a + ++(++1 * 2++)'
  12
  13 # script_prep.py - Primary code generation tool
  14
  15 This translator will accept .script or .scriptlib filenames via the -i flag and generate the .java file via stdout.
  16
  17     ./script_prep.py -i ./filename.script
  18     ./script_prep.py -i ./library.scriptlib
  19
  20 Alternatively an -o flag can be given to specify a custom output target.
  21
  22     ./script_prep.py -i ./src/file.script -o ./built/file.java
  23
  24
  25 # Design Goals
  26
  27 In addition to serving as an important tool for the SWGNext's scripting system, this script serves as a learning tool for the author in language parsing. With that in mind a few notes about the overall design and intent will be kept here for reference.
  28
  29
  30 The first phase of translation is turning the .script or .scriptlib file into a series of "tokens" using the ScriptLexer class. Consider the following simple bit of code:
  31
  32     int a = 5;
  33
  34 The output from the script lexer would be a list of 8 tokens:
  35
  36     INT, 'int'
  37     WS, ' '
  38     ID, 'a'
  39     WS, ' '
  40     EQ, '='
  41     WS, ' '
  42     NUM, '5'
  43     SEMI, ';'
  44
  45 This stream of tokens is then fed into the ScriptParser class which builds a tree of logical constructs held in a ScriptAST.
  46
  47 @TODO: More information here about how ScriptParser generates an AST and what an AST is in laymens terms.
  48
  49 Finally, the generated AST is passed to the JavaGenerator class which turns it into .java code that can then be either dumped to stdout or a specied file target.