Skip to main content

Language Basics

Program Execution​

Decidedly different from most programming languages, Paraflow is a goal-driven language. Its execution consists of an interleaved sequence of the following activities:

  • Executing event handlers: Instructions to handle external events.
  • Planning goals: Creating a plan to achieve desired goals.
  • Executing planned tasks: Instructions that accomplish an atomic goal.

This sequence of activities may take place over milliseconds, hours, days, or even years. As such, there may not be a single instance of running code in memory or an OS process that performs all the activities of a single execution.

A Paraflow instance is the execution sequence associated with a single root goal (i.e., a top-level goal that is not a sub-goal of any other goal). Root goals are created within an event handler and thus these event handlers can be considered the entry point.

Goals​

A Paraflow goal represents a desired activity to perform. The activity may be parameterized by data. A goal instance consists of a name and zero or more specific parameter values.

Goal names are always preceded by the ! symbol.

More on goals: Goals

New goals to be achieved are created in a number of ways:

  • Skill requests from the Paranet may create new goals
  • Event handlers triggered by an external event may create new goals
  • Paraflow rules describe how to decompose an existing goal into sub-goals

These are further described below.

Skill requests​

Paranet actors implemented in Paraflow advertise skills they are able to perform. If the Paranet matches a specific request to the Paraflow actor then the corresponding Paraflow skill handler is triggered which in turn can create a new goal to service the request. See Paranet for details about implementing skills.

Events​

Paraflow can receive WebHook notifications of external events. The event construct defines what to do when some these external event occurs.

More on events: Events

Rules (goal planning)​

The task and rule constructs of Paraflow are used to provide "recipes" for how to achieve goals that match a particular pattern. In the case of rules, they define how to decompose a high-level goal into sub-goals and any sequencing dependencies.

More on rules: Rules

Tasks (achieving goals)​

The task construct defines how to perform a goal. This may be to take some action internally, or it could be to delegate the work to another actor via the Paranet.

More on tasks: Tasks

Comments​

Single-line comments begin with the # symbol and may appear anywhere where whitespace is acceptable. For example:

# This is my main task
!go($uid) {
  with item_detail(id == $uid) { % always exactly one row
  }
}

Variables​

Local variables may be used in any statement block, including the body of events, rules, and tasks. Variable declarations begin with the keyword let followed by the variable name, which must begin with the $ symbol, an initial value, and a terminating semicolon. For example:

let $y = 5 * $x;

Literals​

The following types of fixed values may be used:

  • Strings: These must be enclosed in double quotes: "Hello"
  • Whole numbers: A sequence of digits: 594
  • Decimal numbers: A sequence of digits, decimal point, and second sequence of digits: 2.39
  • Time duration: A sequence of digits followed by a unit (ms, sec, min, hr, hour, hours, day, days): 1 min
  • String templates: Template written are written with single back-quotes that include variable substitutions applied at run time. For example: `Hello $requester` is a template that generates a string a run time with value of the variable $requester substituted into the string.

Built-in functions​

Paraflow has a library of built-in functions. See Built-in Functions for documentation.