farmbot_os/docs/celery_script/celery_script.md

CeleryScript

CeleryScript is an AST definition of commands, rpcs, and functions that can all be executed by Farmbot. The basic syntax is as follows:

%{
  kind: :some_command,
  args: %{non_order_arg1: 1, non_order_arg2: "data"},
  body: []
}

Note the three main fields: kind, args and body. There is also another field comment that is optional. While technically optional, body should be supplied when working with any and all modules in this project.

kind

kind is the identifier for a command. Examples include:

• move_absolute
• sync
• read_status
• wait

Each kind will have it's own set of rules for execution. These rules will define what is required inside of both args and body.

args

args is arguments to be passed to kind. Each kind defines it's own set of optional and required args. Args can any of the following types:

• number
• string (with possible enum types)
• boolean
• another AST.

in the case of another AST, that AST will likely need to be evaluated before executing the parent AST. Examples of args include:

• x
• y
• z
• location
• milliseconds

body

body is the only way a list or array type is aloud in CeleryScript. It may only contain more CeleryScript nodes. This is useful for enumeration, scripting looping etc. Here's a syntacticly correct example:

%{
  kind: :script,
  args: %{},
  body: [
    %{kind: :command, args: %{x: 1}, body: []}
    %{kind: :command, args: %{x: 2}, body: []}
    %{kind: :command, args: %{x: 3}, body: []}
  ]
}

Note there is nesting limit for CeleryScript body nodes, and nodes can even be self referential. Example:

%{
  kind: :self_referencing_script,
  args: %{id: 1},
  body: [
    %{kind: :execute_self_referencing_script, args: %{id: 1}, body: []}
  ]
}