Hacking the RapydScript compiler
=================================

The RapydScript compiler is written in RapydScript itself and uses the
RapydScript import system to modularize its code. The compiler source code is
in the `src` directory. The compiled compiler is by default in the `release`
directory. 

In order to start hacking on the compiler, run the command

```
bin/rapydscript self --complete --test
```

This will generate a build of the compiler in the `dev` directory. Now, the
rapydscript command will automatically use this build, rather than the one in
release. If you want to go back to the release build, simply delete the `dev`
directory.


Code organization
-------------------

The way the compiler works, given some RapydScript source code:

* The source code is lexed into a stream of tokens (`src/tokenzier.pyj`)

* The tokens are parsed into a Abstract Syntax Tree (`src/parse.pyj and src/ast.pyj`)

* During parsing any import statement are resolved (this is different from
  python, where imports happen at run-time, not compile time).

* The Abstract Syntax Tree is transformed into the output JavaScript (`src/output/*.pyj`)

* Various bits of functionality in RapydScript depend upon the *Base Library*
  (`src/baselib*.pyj`). This includes things like the basic container types
  (list/set/dict) string functions such as `str.format()`, etc. The baselib
  is automatically inserted into the start of the output JavaScript.

The RapydScript standard library can be found in `src/lib`. The various tools,
such as the linter, gettext support, the REPL, etc. are in the `tools`
directory.

Tests
--------

The tests are in the test directory and can be run using the command:
```
rapydscript test
```

You can run individual test files by providing the name of the file, as

```
rapydscript test classes
```

Modifying the compiler
-------------------------

Edit the files in the `src` directory to make your changes, then use the
`./try` script to test them.  This script will compile an updated version of
the compiler with your changes, if any, and use it to run the snippet of code
you pass to it.

For example:

```
./try 'print("Hello world")'
```

will compile `print ("Hello world")` and show you the output on stdout. You can
tell it to omit the baselib, so you can focus on the output, with the `-m`
switch, like this:

```
./try -m 'print("Hello world")'
```

You can also have it not print out the JavaScript, instead directly executing the output
JavaScript with the `-x` switch, like this

```
./try -x 'print("Hello world")'
```

If you want to test longer sections of code, you can use the `-f` switch to
pass in the path to a RapydScript file to compile, like this:

```
./try -f myfile.pyj
```

Once you are happy with your changes, you can build the compiler and run the
test suite, all with a single command:

```
./build
```

This will build the compiler with the updated version of itself and then run
the test suite. If all test pass you can commit your changes and send a pull
request :)