====== Introduction to LARA scripts ======

LARA scripts can either be plain JavaScript files with the latest EcmaScript syntax (.js files) or EcmaScript 5 (2009) extended with special constructs (.lara files). Currently the LARA framework supports EcmaScript 2021 for JS files. 

LARA scripts have been moving away from special constructs (e.g., select, apply) in favor of JavaScript-based APIs (e.g., weaver.Query).

==== Aspects ====

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, the first aspect of the script is executed by default.

Aspectdef definition

<code lara>
// The main aspect is the first declared in the file
aspectdef MyFirstAspect
   // aspect code
end

aspectdef ASecondAspect // An aspect that can be called in the main aspect
   // aspect code
end
</code>



==== Aspect Inputs and Outputs ====

Input parameter definition:

<code lara>
input
    funcs,
    opt
end
</code>

Input parameter definition with default values:

<code lara>
input
    funcs = ['kernel'],
    opt = ['unroll', 'interchange', 'tile']
end
</code>

Output definition. Output cannot be initialized inside the **output** block:

<code lara>
output
    optFuncs,
    code
end

optFuncs = [];
code = '';
</code>

==== Calling Aspects ====

Simple aspect call:

<code lara>
call OptimizeProgram();
</code>

Calling an aspect with arguments:

<code lara>
call OptimizeFunctions(functions, optimizations);
</code>

Calling an aspect with named arguments:

<code lara>
call OptimizeFunctions(opt: optimizations, funcs: ['gridIterate']);
</code>


Calling an aspect and retrieving the outputs:

<code lara>
// Current syntax
var optimizer = call OptimizeFunctions(functions, optimizations);

// Previous syntax
call optimizer : OptimizeFunctions(functions, optimizations);

var changedFuncs = optimizer.optFuncs;
var finalCode = optimizer.code;
</code>

Assigning an aspect call to a variable for later use. Can still use input arguments and outputs as shown before:

<code lara>
var optimizer = new OptimizeFunctions(functions, optimizations);

call optimizer(); // or optimizer.call()

var changedFuncs = optimizer.optFuncs;
var finalCode = optimizer.code;
</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();
</code>
==== 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 with the **exec** keyword:

<code lara>
select function{'kernel'} end
apply
    insert before '/* Creating a clone. */';  // add a comment before the function
    def name = 'original_kernel';  // redefine the name of the kernel function
    exec clone('cloned_kernel');  // use a MANET-specific action to create a 'kernel' clone named 'cloned_kernel'
end
</code>

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
</code>

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);  // performed on the same loop as below
    $loop.exec tile(8);  // performed on the same loop as above
end
</code>


If the action returns a result, we can use the following syntax:

<code lara>
   var result = $jp.exec <action_name>;
</code>

If 'result' is a variable that already exists, 'var' can be omitted:

<code lara>
   result = $jp.exec <action_name>;
</code>

The keyword '.exec' can be omitted if you prefix the name of the action with the target join point, and add parenthesis:

<code lara>
  result = $jp.<action_name>();
</code>

==== 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("ls", ["-l", "-v"]);

</code>


==== 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

<code>

larai -i "libs1;libs2"

</code>

=== 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:

<code>

larai -av "{inputFile:'data.json',execute:true,iterations:10}"

</code> 


==== 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, param2) %{
// This code is inserted as-is, without escaping

// To apply the values of parameters, use [[]]
var [[param1]] = [[param2]];

}% end

</code>

Declared codedefs can then be used in the code as functions:

<code lara>

code = CodeTemplate("varName", 2);

</code>