====== LARA General Tips ======

===== Naming Conventions =====

General Javascript styling guides apply, such as:
  * Variable names and functions use camelCase with the first letter in lowercase
  * Class names should be nouns, in use CamelCase with the first letter of each internal word capitalized
  * Global variables use ALLCAPS
  * Private functions/members start with underscore '_' (they will not appear in the generated documentation)

LARA-specific constructs have the following rules:
  * Aspect names follow the same rules of Classes
  * Join point attributes and actions follow the same rules as variable names and functions


/* Furthermore, since importing will evaluate all imported LARA and JS scripts in the same context, to help keep things organized, */

We highly recommend that LARA/JS scripts declare a single global variable or class with the same name as the script (e.g., file Query.js/.lara declares a new class/aspect Query).


===== Regular Expressions =====

Lara supports JavaScript regular expressions, for instance:

<code lara>

var regex = /(return\s+)(10)(\s*;)/;
regex.test("return 10;"); // Returns 'true'

</code>

Since **exec** is a LARA keyword, calling **regex.exec** is not permitted. However, you can access object properties using strings to circumvent this limitation:

<code lara>

(regex['exec']("return 10;"))[2]; // Returns '10'

</code>

Alternatively, you can also use the **match** function in strings:

<code lara>

String('aaaa').match(new RegExp('a*')) // Returns 'aaaa'

</code>

Or you can also use the **match** boolean operator ( **~=** ):

<code lara>

'aaaa' ~= /a*/ // Returns true

</code>

===== Importing LARA Files =====

LARA supports importing LARA files (with extension .lara) that are present in the include path (flag -i) using the keyword **import**. To import a file, you have to use the path to the file from the include folder, using '.' as separator and omitting the extension of the file. For instance, if you add as include the folder ~/foo and you want to import the file ~/foo/bar/Aspect.lara, you can write the following code:

<code lara>

import bar.Aspect;

</code>

Import statements must be the first statements in a LARA file. LARA weavers come bundled with support for a set of imports, which are part of their API (e.g., [[http://specs.fe.up.pt/tools/clava/doc/|Clava API]]).

===== Importing JS Files =====

JS files that are present in an include path can be imported using the LARA keyword **import**. The same rules of importing of LARA files apply. For instance, if you add as include the folder ~/src-js and you want to import the file ~/src-js/bar/Foo.js, you can write the following code:

<code lara>

import bar.Foo;

</code>


If the folder contains both a Foo.lara and a Foo.js, both files are imported, first the LARA file, and then the JS file. This can be useful if the JS file needs specific imports (the keyword **import** is LARA-specific and is not supported by native JS), in this case the imports can be declared in a LARA file and the rest of the code in a JS file. If both files are connected, we recommend using the same name for both files, with corresponding extensions (.lara and .js).

Furthermore, since importing will evaluate all imported LARA and JS scripts in the same context, to help keep things organized, we recommend that LARA/JS scripts declare a single variable/class with the same name as the import (e.g., importing weaver.Query declares a new class Query).

Since LARA scripts are based on an older version of JS (i.e. EcmaScript 5), many recent JavaScript features are not available in LARA code. We recommend using JS files in order to have access to more recent features of JavaScript.

/* Currently the LARA framework supports EcmaScript 2021 for JS files. */
===== Reading/Writing JSON Files =====

LARA supports reading from and writing to JSON objects with the object **Io**:

/* <code lara> */
<code javascript>
import lara.Io;

...

Io.writeJson("file.json", anObject);
var loadedObject = Io.readJson("file.json");
</code>


===== Testing the type of a join point =====

All join points have the attribute ''.joinPointType'', which you might feel tempted to use to check the type of a join point, for further processing. However, it is highly preferable to use ''.instanceOf(<join_point_name>)'' instead.

This respects the join point hierarchy (e.g., "call" and "expr" can both return true) and is more robust than directly checking the name of the join point, i.e. ''$jp.joinPointType === "call"''.