Developer Readme

• 1 Developer information
  • 1.1 Documentation
    • package mars.mike5
    • package mars.mike5.util
    • package mars.mike5.exceptions
    • package mars.mike5.compiler
    • package mars.mike5.debugger
    • package mars.mike5.ga
  • 1.2 Variables
  • 1.3 Plans
    • GA
    • MemArray.java
    • Debugger.java
    • CoreWars.java
• 2 Changelog
  • Version 0.5
  • Version 0.4

1 Developer information

1.1 Documentation

Developed and built using Netbeans 8

Mars interpreter (I hope) finally works correctly, or at least it runs the "validate.red" warrior (part of pMARS distribution) the way it should. It's not "lightning speed" fast, but I was more interested in the correct results as speed. I intend to optimize later.

Found a nice collection of warriors at http://cristal.inria.fr/~doligez/corewar/rc/

Done so far:

package mars.mike5

• basic data structures: MemCell, MemArray, Warrior
• basic enum definitions: OpCode, AddressingMode, Modifier
• Application: CoreWars
• MARS options: Options
• MemArray
  • MemCell[] core
  • List warriors
  • dump(Writer file)
  • execute(warrior) - interprets the next instruction of the warrior
    • based on ICWS 94 Proposed Standard implementation of interpreter http://www.koth.org/info/icws94.html

package mars.mike5.util

• CommandLine : command line parser
• TokenizedExpression:
  • The type of the expression parsed is determined by the class implementing the ExpressionParser interface
  • CompilerParser parses expressions for the compiler and support for labels, and expression evaluation
  • operator priority
  • parentheses
• ExpressionParser parses expressions to evaluate GA fitness function. Each function evaluates to a real number (double) result. The mode for binary operations is the same as Java, i.e. if one of the operands is a real number, the result is a real number, otherwise it is an integer. The fitness evaluation supports scalar variables and 1-D array variables. These are always provided by the system and cannot be changed.
• ExpressionParser and CompilerParser operators & priority:

  Arithmetic:
  
      +   addition or unary plus
      -   subtraction or unary minus
      *   multiplication
      /   division
      %   modulo (remainder of division) Works only on Integers!
  
  Comparison:
      ==  equality
      !=  inequality
      <   less than
      >   greater than
      <=  less than or equal
      >=  greater than or equal
  
  Logical:
      &&  and
      ||  or
      !   unary negation
  
  Comparison and logical operators return 1 for true and 0 for false.
  Parentheses can be used to override this precedence order:
  
  1) ! - + (unary)
  2) * / %
  3) - + (binary)
  4) == != < > <= >=
  5) &&
  6) ||
  

package mars.mike5.exceptions

• CompileErrorException
• InvalidParamException
• TooManyParamsException

package mars.mike5.compiler

• Compiler:
  • basic compiler,
  • supports redcode,
  • comments, 'org' and 'end' meta-instructions
  • ;assert
  • ;name
  • ;author
  • EQU support, including multiline.
  • FOR/ROF loops
  • multiple labels per instruction supported (each label in its own line)

• CompiledWarrior: contains memory cells for compiled warrior, its id and name. This is temporary only, and is later copied into core.

  • Support classes:
    • SymbolicMemCell

• passes pMars 'validate.red' ;)

package mars.mike5.debugger

• a simple debugger interface, capable of opening multiple memory inspection windows, and one window for each warrior. Marks selected memory location, or the next warrior instruction. Also a P-space dump window for each warrior may be opened. It is possible to edit core/P-space contents in place.

package mars.mike5.ga

• this package contains all the GA stuff and the handling of the generations. Each generation can be archived for analysis. The type of archive is folder or Zip. The contents of the archive are:
  • MARS settings
  • all the warriors that were used for this generation
  • their scores
  • all the warriors that are created through GA crossover and mutation

1.2 Variables

See user [Readme].

1.3 Plans

Still to do (order of preference):

GA

• add UI window with real-time reporting
• current score of each warrior
• results after each generation

MemArray.java

• make interpreter faster (maybe)

Debugger.java

• add 'Finish round' button

CoreWars.java

• add pMARS (and maybe KoTH) compatible output
• add other other ICWS language variants as well

Write great documentation and comment everything ;)

2 Changelog

Version 0.5

• Added CLI parameter -GC (--generate-config) which generates XML configuration for GA. The name/location of the XML file is passed as a parameter. The configuration also includes any warrior files found in the same folder as XML file.

Version 0.4

• Added all pMars supported operators
• added ;assert
• multiple labels per instruction
• SPL honors the MAXPROCESSES setting
• Assignment and variables added
• Added P-space to warriors
• Added P-space inspection window to debugger
• LDP and STP implemented
• CLI option -S and hide P-space inspection in debugger when necessary
• debug option changed to '-e'
• addresses larger than 75% of CORESIZE are now displayed as negative in debugger
• load the first warrior at address 0
• Core/P-space editing in debugger
• Added CLI option -F
• Added CLI options -c and -p
• Debugger now dumps each warrior
• Added CLI options -b and -l
• Debugger assembly warrior dump flushes with every println
• pMARS compatible warrior assembly dump
• added inspect size spinner to Debugger window
• added support for multiline EQU (preprocessor)
• added support for FOR/ROF loops
• added CLI parameter -r
• added CLI parameter -=