Variables

There are two kinds of variables: routing variables and entity variables.

Routing variables can be persisted (which means the variable is set via the '=' operator (or '+', '-') in the persistent variable set (see below)) and modified during the course of the existence of the circuit, making this a simple mechanism for protocol compression, whereas context entities may persist variables (meaning: they use the '=' modifier to set persistent variables) for all their members to keep for the entire duration of existence of the context, making it a decentralized storage vehicle.

Each context has it's own set of persistent entity variables. If the _context routing variable is NOT set persistent entity variables MUST NOT be changed. This means that persistent entity variable changing modifiers can only be used when _context is set, and thus updating persistent entity variables can only be done by a context.

Should a modifier change a persistent entity variable but _context is not set, the violation SHOULD be acquitted with a _failure_unsupported_state_persistent error packet and the circuit MAY be terminated. (See also Spec:Entity).

NOTE: In theory also unicast entity communications between a _source and a _target could each define a set of persistent variables. Such entity state (as opposed to context state) is however currently not supported as it raises storage requirements of PSYC implementations more than it is likely to prove useful. It is reserved for possible future use.

Out-of-context communication may however still refer to persistent variables from in-context communication in its psyctext template.

Each packet defines a set of current variables which may be different from the persistent set of variables. When passing the variables to an application, the programming interface SHOULD merge current routing and entity variables into a single structure.

See also Spec:State.

routing and entity modifiers

Each packet comes with a set of routing modifiers and entity modifiers. The routing modifiers belong to the routing-header and are separated by a newline from the entity modifiers (entity-modifier).

The routing modifiers modify the current and persistent routing variables. The entity modifiers modify the current and persistent entity variables.

This means that after routing modifiers (routing-mods) have been processed the persistent variables for the sending entity need to be loaded (persistent context slave) before the process of handling content is started (entity-modifier).

Recommendation: The modification of incoming and outgoing routing variables should be done by the circuit whereas entity variable modifications are generated by the entities and received by context slaves.

Current and persistent variable handling

When a packet is being parsed, the modifiers modify the set of current and persistent routing and entity variables. To do so, the set of current variables is initialized by the set of persistent variables before the modifiers are applied.

After the packet has been processed, the current routing and entity variables are the significant variables that belong to the instance of the parsed packet.

NOTE: You have to make sure that you don't apply the changes to the permanent routing variables until the whole routing header has been parsed. Same with the entity variables.

Operators

• = – The variable is modified in the set of current variables and the set of persistent variables. If no variable name is provided the persistent variables and current variables are deleted.
• : – The variable is only modified in the set of current variables.
• + – For _list variables, the elements in the modifier argument are appended to the permanent variables and the current variables. Further types MAY define custom uses of this modifier.
• - – For _list variables, the elements in the modifier argument are removed from the permanent variables and the current variables. Further types MAY define custom uses of this modifier.
• ? – State sync request.
• !$@%&*/#;, – Reserved for as yet undefined state operations.