arrai

README

Sysl arr.ai (WIP)

This package contains experimental arr.ai code that operates on Sysl models. It seeks to:

• Demonstrate how to use arr.ai to work with Sysl models.
• Replicate sysl's various commands in a more concise, functional style.
• Introduce new capabilities such as relational modelling and data flow analysis.

Each script has an accompanying Markdown file describing the logic and output.

Usage

To keep things simple and consistent, all scripts currently work with the same model.sysl spec. This spec will evolve over time to contain the full range of Sysl features and patterns to stress test the scripts.

To run all the scripts at once, run:

make

To run a particular script, run make for it's output target. For example, to generate the SVG output of the data_diagram.arrai script, run:

make data_diagram.svg

For diagram targets (svg and png), make will use the arr.ai script to produce the PlantUML output, then attempt to render it with a PlantUML server and save the result.

You can of course run the scripts directly as well. For example:

arrai run data_diagram.arrai > out/data_diagram.puml

Development

Loading the model

Many of the scripts will start by importing the default model.sysl model like so:

let model = //{./load_model};
...

This actually loads the proto-encoded out/model.pb file, so if model.sysl is changed, out/model.pb must be regenerated like so:

sysl protobuf --mode=pb model.sysl > out/model.pb

If an extra command line arg is provided to arrai run, the load_model script treats it as a path to a .pb-encoded Sysl model to use instead.

Environment

To develop additional arr.ai scripts, you're encouraged to use Visual Studio Code with the arrai extension.

To speed up the edit/refresh cycle, install the Save and Run extension and configure it with:

"saveAndRun": {
    "commands": [
        {
            "match": "\\.arrai$",
            "cmd": "echo; arrai run ${file}",
            "useShortcut": false,
            "silent": false
        }
    ]
}

This will make VS Code automatically run the script every time you save it (after printing a newline for clarity).

For more comprehensive testing, you can also run make on every save of every file in this directory.

Documentation

Index

• func EvaluateBundle(bundle []byte, args ...string) (rel.Value, error)
• func EvaluateGrammar(wbnf, rule, source string) (rel.Value, error)
• func EvaluateMacro(wbnf, rule, tx, source string) (rel.Value, error)
• func EvaluateMacroSimple(wbnf, rule, source string) (rel.Value, error)
• func EvaluateScript(arraiScript string, scriptParams ...interface{}) (rel.Value, error)
• func SyslModuleToValue(module *sysl.Module) (rel.Value, error)
• func SyslPbToValue(pbPath string) (rel.Value, error)
• func ToStringInterfaceMap(x interface{}) map[string]interface{}
• func ToStrings(x interface{}) []string
• type ExecutionError
  • func (e ExecutionError) Error() string

Functions

func EvaluateBundle

func EvaluateBundle(bundle []byte, args ...string) (rel.Value, error)

RunBundle runs an arr.ai bundle with the passed parameters set as //os.args[1:]. It help to pass Go's type parameters to arrai script explicitly.

func EvaluateGrammar

func EvaluateGrammar(wbnf, rule, source string) (rel.Value, error)

EvaluateGrammar parses a wbnf grammar from source, uses the grammar (and a root rule) to parse a source string, and returns the resulting AST.

func EvaluateMacro

func EvaluateMacro(wbnf, rule, tx, source string) (rel.Value, error)

EvaluateMacro parses a wbnf grammar from source, uses the grammar (and a root rule) to parse a source string, transforms the resulting AST with the tx function (arr.ai source) and returns the output.

func EvaluateMacroSimple

func EvaluateMacroSimple(wbnf, rule, source string) (rel.Value, error)

EvaluateMacroSimple parses a wbnf grammar from source, uses the grammar (and a root rule) to parse a source string, transforms the resulting AST with the simpleTransform function from arrai/contrib/util, and returns the output.

func EvaluateScript

func EvaluateScript(arraiScript string, scriptParams ...interface{}) (rel.Value, error)

EvaluateScript evaluates script with passed parameters. It help to pass Go's type parameters to arrai script explicitly. TODO: will move it to arrai when it is ready.

func SyslModuleToValue

func SyslModuleToValue(module *sysl.Module) (rel.Value, error)

SyslPbToValue serializes a Sysl protobuf message to an arr.ai value.

func SyslPbToValue

func SyslPbToValue(pbPath string) (rel.Value, error)

SyslPbToValue loads a Sysl protobuf message from a path and serializes it to an arr.ai value.

func ToStringInterfaceMap

func ToStringInterfaceMap(x interface{}) map[string]interface{}

func ToStrings

func ToStrings(x interface{}) []string

Types

type ExecutionError

type ExecutionError struct {
	Context  string
	Err      error
	ShortMsg string
}

ExecutionError encapsulates detailed error msgs from arr.ai runtime.

func (ExecutionError) Error

func (e ExecutionError) Error() string