This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
doc:lara:tips [2022/01/15 19:39] jbispo |
doc:lara:tips [2022/01/15 20:20] (current) jbispo |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== LARA General Tips ====== | ====== LARA General Tips ====== | ||
- | The LARA language is JavaScript (plain JavaScript is valid LARA code) extended with custom syntax oriented for source code analysis and transformation. | + | ===== Naming Conventions ===== |
- | Recently LARA has been moving away from language-specific constructs (e.g., select, apply) | + | General Javascript styling guides apply, such as: |
- | ==== Aspects ==== | + | * Variable names and functions use camelCase with the first letter in lowercase |
+ | * Class names should be nouns, in use CamelCase with the first letter | ||
+ | * Global variables use ALLCAPS | ||
+ | * Private functions/ | ||
- | Aspects are regions of code where LARA syntax can be used, and are similar to functions. They are also the entry point of a LARA script, | + | LARA-specific constructs have the following rules: |
+ | * Aspect names follow | ||
+ | * Join point attributes and actions follow | ||
- | Aspectdef definition | ||
- | <code lara> | + | /* Furthermore, |
- | // The main aspect is the first declared | + | |
- | aspectdef MyFirstAspect | + | |
- | // aspect code | + | |
- | end | + | |
- | aspectdef ASecondAspect // An aspect | + | We highly recommend |
- | // aspect code | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | + | ||
- | + | ||
- | ==== Aspect Inputs and Outputs ==== | + | |
- | + | ||
- | Input parameter definition: | + | |
- | + | ||
- | <code lara> | + | |
- | input | + | |
- | funcs, | + | |
- | opt | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | Input parameter definition with default values: | + | |
- | + | ||
- | <code lara> | + | |
- | input | + | |
- | funcs = [' | + | |
- | opt = [' | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | Output definition. Output cannot be initialized inside the **output** block: | + | |
- | + | ||
- | <code lara> | + | |
- | output | + | |
- | optFuncs, | + | |
- | code | + | |
- | end | + | |
- | + | ||
- | optFuncs = []; | + | |
- | code = ''; | + | |
- | </ | + | |
- | + | ||
- | ==== Calling Aspects ==== | + | |
- | + | ||
- | Simple aspect call: | + | |
- | + | ||
- | <code lara> | + | |
- | call OptimizeProgram(); | + | |
- | </ | + | |
- | + | ||
- | Calling an aspect with arguments: | + | |
- | + | ||
- | <code lara> | + | |
- | call OptimizeFunctions(functions, | + | |
- | </ | + | |
- | + | ||
- | Calling an aspect with named arguments: | + | |
- | + | ||
- | <code lara> | + | |
- | call OptimizeFunctions(opt: | + | |
- | </ | + | |
- | + | ||
- | + | ||
- | Calling an aspect and retrieving the outputs: | + | |
- | + | ||
- | <code lara> | + | |
- | // Current syntax | + | |
- | var optimizer = call OptimizeFunctions(functions, | + | |
- | + | ||
- | // Previous syntax | + | |
- | call optimizer : OptimizeFunctions(functions, | + | |
- | + | ||
- | var changedFuncs = optimizer.optFuncs; | + | |
- | var finalCode = optimizer.code; | + | |
- | </ | + | |
- | + | ||
- | Assigning an aspect call to a variable | + | |
- | + | ||
- | <code lara> | + | |
- | var optimizer = new OptimizeFunctions(functions, | + | |
- | + | ||
- | call optimizer(); | + | |
- | + | ||
- | var changedFuncs = optimizer.optFuncs; | + | |
- | var finalCode = optimizer.code; | + | |
- | </ | + | |
- | + | ||
- | Aspects can also be called inside Javascript files (.js). You need to build the aspect object and reference the complete path, separated by dollar signs ($): | + | |
- | + | ||
- | <code lara> | + | |
- | // Calling aspect MeasureEnergy from inside a .js file | + | |
- | + | ||
- | (new lara$profiling$Energy$EnergyTest()).call(); | + | |
- | </ | + | |
- | ==== Using LARA Actions ==== | + | |
- | + | ||
- | Actions are used inside apply statements. There are two default actions, **insert** and **def**. Then, it is possible to use weaver-specific actions, which are called | + | |
- | + | ||
- | <code lara> | + | |
- | select function{' | + | |
- | apply | + | |
- | insert before '/* Creating a clone. */'; | + | |
- | def name = ' | + | |
- | exec clone(' | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | When calling an action we can specify any join point in the chain to be the action target: | + | |
- | + | ||
- | <code lara> | + | |
- | select function.loop end | + | |
- | apply | + | |
- | $loop.exec tile(8); | + | |
- | $function.insert before '/* This function was transformed. */'; | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | It is possible to omit the target, the last join point in the chain is used: | + | |
- | + | ||
- | <code lara> | + | |
- | select function.loop end | + | |
- | apply | + | |
- | exec unroll(2); | + | |
- | $loop.exec tile(8); | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | + | ||
- | If the action returns a result, we can use the following syntax: | + | |
- | + | ||
- | < | + | |
- | var result = $jp.exec < | + | |
- | </ | + | |
- | + | ||
- | If ' | + | |
- | + | ||
- | <code lara> | + | |
- | | + | |
- | </code> | + | |
- | + | ||
- | The keyword ' | + | |
- | + | ||
- | <code lara> | + | |
- | result = $jp.< | + | |
- | </ | + | |
- | + | ||
- | ==== Calling shell commands ==== | + | |
- | + | ||
- | You can invoke shell commands from LARA using the function cmd. The first argument is the command, and the second an array with the arguments for the command: | + | |
- | + | ||
- | <code lara> | + | |
- | + | ||
- | cmd(" | + | |
- | + | ||
- | </ | + | |
- | + | ||
- | + | ||
- | ==== Using LARA from the Command Line ==== | + | |
- | + | ||
- | === Include Folder === | + | |
- | + | ||
- | To add include folders, use the flag -i. To add more than one folder, use double quotes and separate the folders with the file separator character of your current system | + | |
- | + | ||
- | < | + | |
- | + | ||
- | larai -i " | + | |
- | + | ||
- | </ | + | |
- | + | ||
- | === Passing Arguments to the Aspect === | + | |
- | + | ||
- | To pass arguments to the top-level aspect use the flag -av. The input is a JSON representation of the input: | + | |
- | + | ||
- | < | + | |
- | + | ||
- | larai -av " | + | |
- | + | ||
- | </ | + | |
- | + | ||
- | + | ||
- | ==== Codedef Sections ==== | + | |
- | + | ||
- | To insert sections of code that span several lines, you can define codedef sections, which act as templates. Example: | + | |
- | + | ||
- | <code lara> | + | |
- | + | ||
- | codedef CodeTemplate(param1, | + | |
- | // This code is inserted as-is, without escaping | + | |
- | + | ||
- | // To apply the values of parameters, use [[]] | + | |
- | var [[param1]] = [[param2]]; | + | |
- | + | ||
- | }% end | + | |
- | + | ||
- | </ | + | |
- | + | ||
- | Declared codedefs can then be used in the code as functions: | + | |
- | + | ||
- | <code lara> | + | |
- | + | ||
- | code = CodeTemplate(" | + | |
- | + | ||
- | </ | + | |
- | ====== Miscellaneous ====== | ||
- | ==== Regular Expressions ==== | + | ===== Regular Expressions |
Lara supports JavaScript regular expressions, | Lara supports JavaScript regular expressions, | ||
Line 254: | Line 54: | ||
</ | </ | ||
- | ==== Importing LARA Files ==== | + | ===== 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 ' | 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 ' | ||
Line 266: | Line 66: | ||
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:// | 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:// | ||
- | ==== Importing JS Files ==== | + | ===== Importing JS Files ===== |
- | All JS files (with extension .js) that are present in folders of the include path are automatically evaluated before any LARA file. However, there is a mechanism for importing specific JS files at the same time as LARA 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/ |
- | + | ||
- | When the name of a folder of the include path ends with ' | + | |
<code lara> | <code lara> | ||
Line 283: | Line 81: | ||
Furthermore, | Furthermore, | ||
- | Since LARA is 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. | + | 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. |
- | ==== Reading/ | + | |
+ | /* Currently the LARA framework supports EcmaScript 2021 for JS files. | ||
+ | ===== Reading/ | ||
LARA supports reading from and writing to JSON objects with the object **Io**: | LARA supports reading from and writing to JSON objects with the object **Io**: | ||
Line 299: | Line 99: | ||
- | ==== Testing | + | ===== Testing |
+ | |||
+ | All join points have the attribute '' | ||
- | To test if a join point is of a certain type, use the attribute '' | + | This respects the join point hierarchy (e.g., " |