07.heavy_lang.md

The Heavy Audio Programming Language Specification

Graph

The graph object is the top-level object which can be loaded from file. It is a dictionary with four keys.

• imports: A list of paths in which to look for abstractions.
• args: A dictionary of objects defining which arguments this graph (i.e. abstraction) can take.
• objects: A dictionary defining the objects in this graph.
• connections: A list of connections between objects in this graph.

imports

An optional list of paths defines where abstractions can be found. By default, the following paths are implicitly searched in order before any of the listed paths.

1. Low-level Heavy objects
2. Heavy standard library
3. Local path
4. Imported paths

Note that if an abstraction with the same name is found in more than one path, the first one found is used.

Paths may be relative or absolute. If they are relative, they are relative to the location of the graph which is being defined.

{
  "imports": [
    "path/to/dir",
    "path/to/other/dir"
  ]
}

args

This key defines the parameters which a graph or object can take. Each element in the args list is a dictionary containing a set of keys describing that argument.

In this example, the graph has one parameter, fc. It is a float, and is not required to be supplied when the graph is instantiated. This parameter defaults to a value of 0.0. If a parameter is required, the default value may be set as null.

{
  "args": [
    {
      "name": "fc",
      "type": "float",
      "description": "The cutoff frequency (Hz).",
      "default": 0.0,
      "required": false
    }
  ]
}

objects

The objects key declares a dictionary of objects in this graph. Each key is a unique identifier for the object. See below for a definition of object dictionaries.

{
  "objects": {
    "add_0": {
      "type": "add",
      "args": {
        "k": 5
      },
      "properties": {
        "x": 100,
        "y": 200
      }
    }
  }
}

connections

A list of connection objects between the objects in the graph. Each connection is defined by its type, as well as a from starting point and a to termination point composed of an an object id and a let index.

A connection type can be any one of:

1. -->: a control connection
2. -~>: a connection that can be either control or signal, the exact type of which must be resolved at compiletime.
3. ~f>: a float signal connection
4. ~i>: an int signal connection

{
  "connections": [
    {
      "type": "-->",
      "to": {
        "id": "add_0",
        "inlet": 0
      },
      "from": {
        "id": "loadbang_0",
        "outlet": 0
      }
    }
  ]
}

Object

An object dictionary defines which object is required, as well as arguments, properties, or annotations defining its behaviour. The standard keys include:

• type
• args
• annotations

{
  "add_0": {
    "type": "add",
    "args": {
      "k": 5
    },
    "properties": {
      "x": 100,
      "y": 200
    }
  }
}

type

This key defines which object or abstractions the object refers to. If the object type are resolved according to the Heavy path importation priority list as described above.

args

Object arguments are described, and are object-specific. If a graph argument should be passed to an object in the graph, the argument an be referred to by appending a $ to the from of the argument name.

{
  "add_0": {
    "args": {
      "k": "$fc"
    }
  }
}

This argument value will be resolved at compile time, with a defined default value being used if none is available.

properties (optional)

An optional properties key may be supplied to give user-defined to UI-related information. This might include the x, y position of an object in a patch. The parameters dictionary is not used in the compilation process.

annotations (optional)

Some objects may be annotated in order to provide additional hints to the compiler, or to modify standard behaviour. Three annotations are available, scope, static, and const.

• scope: Three scoping rules are available, public, protected, private. By default all scoping is private.
  • public: The object is visible anywhere in the entire patch.
  • protected: The object is visible anywhere from the super down.
  • private: The object is only visible in the local graph. The canonical example is scoping the visibility of tables. By default they are only visible in their own graph, but can be given global visibility by annotating them with the public keyword.
• static: boolean Only one of this object exists per abstraction. Even if multiple instances of an abstraction are created, all instances refer to the one instance of the static named object. By default objects are not static.
• const: boolean The value of this object never changes. By default objects are not const.

{
  "annotations": {
    "scope": "public",
    "static": true,
    "const": true
  }
}

Considerations

Combinations of scope and static may have slightly different meanings typically found in other languages.

• public static: The named object is visible globally, but there can only be one instance of it. This is effectively the default of all public objects. The static keyword prevents errors due to the redefinition of the object.
• protected static: TODO(mhroth) not implemented yet
• private static: The named object is only visible in graphs declared from a particular Heavy file.

Objects and Scoping

There is a specific set of objects to which scoping rules apply. These are:

• send / s

  • scope: public, protected, private
  • static: N/A
  • const: N/A
  • unique: false Any number of send objects may exist at any level.

• receive / r:

  • scope: public, protected, private
  • static: N/A
  • const: N/A
  • unique: false Any number of receive objects may exist at any level.

• table:

  • scope: public, protected, private
  • static: true, false If true, only one of that table exists, regardless of how many times it is declared.
  • const: the values of the table may never change.
  • unique: true All tables must be unique in their scope.

• var:

  • scope: public, protected, private
  • static: allowed
  • const: allowed
  • unique: true All variables must be unique in their scope.