== About the project ==

This project is part of the free/open-source platform for developing rule-based
machine translation systems, Apertium. And it is being developed as part of the
Google Summer of Code 2011.

The aim of the project is to create a simple compiler and VM for the transfer
files of Apertium.

== Requirements ==

 - Python 3.

== Execution ==

For now you can just run the python module you want (compiler or vm) directly
from the source code using a python3 interpreter, for example:

 > python3 src/compiler (options), or, 
 > python3 src/vm (options)

=== Options ===

To see the options of each module you can run the above command with the -h flag
to see the help of the module, with the explanation of the different options.

=== Compiler ===

To run the compiler you only need a t?x file as input and the compiler will
generate its assembly representation. For example:

 > python3 src/compiler -i test/data/apertium-en-ca.en-ca.t1x -o output.v1x

You can also use stdin and stdout as input and output, for example:
 
 > cat test/data/apertium-en-ca.en-ca.t1x | python3 src/compiler > output.v1x

Finally, if you want to generate debug information, like comments for some of the
assembly instruction, you can use the -d flag:

 > python3 src/compiler -i test/data/test_macro_2.t1x -d compiler.log

=== VM ===

The VM can run code generated by the compiler, for now, you can use the -c option
to set the code to run and the VM, automatically, will detect from which transfer
stage it is and will run it accordingly. For example:

 > python3 src/vm -c code_file -i input_file -o output_file

 > python3 src/vm -c test/expected_output/compiler/apertium-en-ca.en-ca.v1x 
   -i test/input/chunker/rule_all_nounplural 

You can also use stdin and stdout as input and output, for example:

 > cat input_file | python3 src/vm -c code_file > output_file

And using this last option, you can use piping to run an input file through all
the stages of the advanced transfer, for example:

 > cat input_file | python3 src/vm -c chunker_code | python3 src/vm -c
   interchunk_code | python3 src/vm -c postchunk_code

NOTE: The input used by the vm is the generated by the -b option of lt-proc, you
can find some example inputs in the tests/input folders for each transfer stage.

 - input_file: you can find some in test/input/<transfer stage>
 - code_file: you can find some in test/expected_output/compiler

== Tests ==

You can run some simple tests for the compiler with the script
run-tests-compiler.sh and some for the VM with the script run-tests-vm.sh. Both
found in the test folder.