====== larai ======

The LARA interpreter is a tool able to interpret an Aspect-IR and execute its aspects. **larai**, in its basis, can execute any arbitrary imperative code and execute tools and commands that are not part of **larai**. However, this interpreter cannot carry out weaving-related tasks, such as selecting points in the code and apply actions. In order to do so, **larai** can be connected to a [lara:docs:weavingengine|weaving engine] that is responsible of parsing the target source code, select join points and retrieve attribute information, apply actions, and generate the resulting code.

**larai** as a standalone has been used for different purposes:
  * As scripting language
  * Tools execution
  * Coordination of a compilation flow (e.g. instrumentation->optimization->compilation->execution->profile).
  * Design-space exploration (e.g. using previous objective)

**NOTE:** **larai** has a builtin [[lara:docs:larac|larac]], meaning that **larac** is not required as a separated tool for lara->Aspect-IR compilation and hence a .lara file may be given as input argument of **larai**.

===== Execution =====
This interpreter may be executed in two different ways: by command line for immediate execution of a lara file or by an IDE for developing and execute/test aspects.

==== Command Line ====
**larai** is an executable jar file (download [[http://specs.fe.up.pt/tools/larai.jar| here]]) that always expects a .lara|.xml file as the first input argument and has a set of optional arguments. If a .lara file is given then larac is automatically executed, otherwise, if a .xml is given, the interpreter assumes that file as the Aspect-IR and attempts to execute. larai accepts the options defined in the following table. A special note must be given to the last option as this option is not actually an option of larai but to portray an additional option that a weaving engine may contain. These additional options always have a short option defined in uppercase to differ to *larai* options.

<code>
usage: <aspect.lara> [options] [-c <file>]  | -c <file>[-g]
 -c,--config <file>              configuration file with defined options
 -g,--gui                        open in GUI mode
 -h,--help                       print this message
 -v,--version                    print version information and exit
 -av,--argv <arguments>          arguments for the main aspect
 -m,--main <aspect>              select main aspect
 -d,--debug                      show all process information
 -o,--output <dir>               change output dir
 -p,--workspace <dir>            change the working directory
 -b,--verbose <level>            verbose level
 -t,--tools <tools.xml>          location of the tools description
 -r,--report <file_name.json>    Output file for the main aspect, in JSON
                                 format
 -i,--includes <dir>             includes folder (imports files with
                                 extensions: lara, jar, js, class)
 -j,--javascript                 show the javascript output in the same
                                 stream as the application's output
 -l,--log <fileName>             outputs to a log file
 -e,--metrics <file_name.json>   Output file for the weaving metrics
 -O, --other                     An option related to a specific weaving engine
</code>

The following table provides a further explanation of the larai options. Note that option -g (GUI mode) can only be used with -c (config file) option and without specifying a lara file.

^ Short Option  ^ Long option   ^ Argument 	^ Description          ^
| -c		| --config 	| <file>		 	| configuration file with defined options (can be created and edited in GUI mode)|
| -g		| --gui       |  - 			 	| open in GUI mode (IDE)|
| -h		| --help      |  - 			 	| print the options available in larai and the weaving engine|
| -v		| --version   |  -              | print version information and exit|
| -a		| --argv		| <arguments>   | arguments for the main aspect|
| -m		| --main 		| <aspect>      | define aspect to be executed as the main aspect |
| -d		| --debug     |  -              | show all process information in the log (includes debug information from larac if applicable)|
| -o		| --output	| <dir>             | change output directory of the resulting, generated code|
| -p		| --workspace	| <dir+>         | change the directory(ies) and/or file(s) the weaver engine must compile. Separate paths with ";"|
| -b		| --verbose	| <level>           | change the message level (default: 3):\\ 0: none\\ 1: errors\\ 2: errors and warnings\\ 3: errors, warnings and logs |
| -t		| --tools		| <tools.xml>   | location of the xml file that describe the tools one may execute in a LARA aspect.|
| -r		| --report	| <file_name.json>  | write in a file the outputs of the main aspect, in JSON format|
| -i		| --includes	| <dir+>         | specify directories containing files to import. imports files with extensions: lara, jar, js, class). separate paths with ";"|
| -j		| --javascript|  -              | this option can be used when --log option is used. However the lara compilation/interpretation can be redirected by the --log option, the actual output of the aspects remains the same. Activating this option forces larai to redirect the execution's output to the same log file |
| -l		| --log		| <fileName>        | outputs to a log file instead of the default (console) output |
| -e		| --metrics	| <file_name.json>  | specify file for the output metrics of larai |

==== IDE ====


===== Weaver Engine API =====

==== Default Weaver ====


==== New Weaving Environment ====


===== Report Weaving Metrics =====