API

Embedding / API

You might want to use AutoMaTA for your own projects, and make use of it's API.

To get started, you might want to understand how default automata behaves when running a file.

Importing libraries

In order for your script to get parsed, it first needs to get expanded with the libraries imported via +<lib_name>.

Simply add all your libraries (via File.ReadFile or other means) to the LibraryData.libs dictionary. From here, automata will automatically expand the source script with the library contents.

Importing and parsing the file

After initializing libraries, read your file or script from whatever source. Then, pass it through the ProgramParser.

In order to do this, create a new instance of ProgramParser, and parse the script source as follows:

var parser = new ProgramParser(amtascript);
parser.Parse();
// amtascript is the loaded contents of the script

Initializing the program scope

Automata uses the ProgramScope class to store all the data related to functions / variables in your script. Using this, you can run every script in their own separate scope, or run multiple on the same one.

Simply create a scope by calling the constructor with the scope's name as follows:

var scope = new ProgramScope("<scope name>");
// NOTE: the scope's name is only used for debug logging

You now can add custom variables or naive functions to your scope, and they can be invoked from within the script. One example is the default print method:

// register print function
scope.RegisterFunction("print", new NativeFunction((scope) => {
    Variable? var_str = scope.GetVariable("print_string");
    if (var_str == null)
        var_str = scope.GetVariable("print_0");
    if (var_str == null)
    {
        Logger.Print("[AutoMaTA] Print function called, but no parameter provided. Use $print_string or $print_0");
        return;
    }
    if (var_str.var_type != Variable.VariableType.String)
    {
        Logger.Print("[AutoMaTA] Print function called, but argument was not string");
        return;
    }
    Logger.Print(var_str.str_value!);
    scope.UnregisterVariable(var_str.name);
    // NOTE: parameter variable is deleted, to avoid erroneous calls to the print function, and two allow different parameter names
}));

This is also the place you would register any extensions such as the ArraysExtension or StringExtension.

Importing the parsed script into the program scope

In order for your script to run properly, the parsed information needs to get imported in the scope.

Simply call the .ImportParser method of the scope object as follows

scope.ImportParser(parser);
// scope is the ProgramScope
// parser is the ProgramParser

Calling the main function of the script

You can now begin execution of your script. Simply call the main function on the scope, or any other functions you might need to call as follows

scope.GetFunction("main")!.Call(scope);
// NOTE: even though you are referencing the scope when getting the function definition, you still need to pass it to the Call method

Summary

This is more or less the same behaviour the default CLI has.

Additional settings

Additionaly, you can enable debug message logging (debug messages generated by automata) or limit / disable the limit of while loops. By default, while loops are capped at 10000 iterations, to avoid endless execution of a function.

Config.PrintDebugMessages controls rather to print debug messages or not

Config.MaxWhileLoops controls the maximum number of iterations a while loop can do. You can disable it by setting it to int.MaxValue

You can also change the default logger, by changing the Logger.logFunction field, to any function which takes in a single string parameter.