Directives

Directives are system values that modify the encoding context.

Syntactically, a directive is a top-level s-expression annotated with $ion. Its first child value is an operation name. The operation determines what changes will be made to the encoding context and which clauses may legally follow.

$ion::
(operation_name
    (clause_1 /*...*/)
    (clause_2 /*...*/)
    /*...more clauses...*/
    (clause_N /*...*/))

In Ion 1.1, there are three supported directive operations:

  1. module
  2. import
  3. encoding

Top-level bindings

The module and import directives each create a stream-level binding to a module definition. Once created, module bindings at this level endure until the file ends or another Ion version marker is encountered.

Module bindings at the stream-level can be redefined.

tip

The add_macros and add_symbols system macros work by redefining the default module (_) in terms of itself.

This behavior differs from module bindings created inside another module; attempting to redefine these will raise an error.

module directives

The module directive binds a name to a local module definition at the top level of the stream.

$ion::
(module foo
    /*...imports, if any...*/
    /*...submodules, if any...*/
    (macro_table /*...*/)
    (symbol_table /*...*/)
)

import directives

The import directive looks up the module corresponding to the given (name, version) pair in the catalog. Upon success, it creates a new binding to that module at the top level of the stream.

$ion::
(import
    bar               // Binding
    "com.example.bar" // Module name
    2)                // Module version

The version can be omitted. When it is not specified, it defaults to 1.

If the catalog does contain an exact match, this operation raises an error.

encoding directives

An encoding directive accepts a sequence of module bindings to use as the following stream segment's encoding module sequence.

$ion::
(encoding
    mod_a
    mod_b
    mod_c)

The new encoding module sequence takes effect immediately after the directive and remains the same until the next encoding directive or Ion version marker.

Note that the default module is always implicitly at the head of the encoding module sequence.