Module ZEN

Zencode language parser

Zencode is a Domain Specific Language (DSL) made to be understood by humans and inspired by Behavior Driven Development (BDD) and Domain Driven Design (DDD).

The Zenroom VM is capable of parsing specific scenarios written in Zencode and execute high-level cryptographic operations described in them; this is to facilitate the integration of complex operations in software and the non-literate understanding of what a distributed application does. A generic Zencode looks like this:

Given that I am known as 'Alice'

When I create my new keypair

Then print my data

This section doesn't provide the documentation on how to write Zencode, but illustrates the internals on how the Zencode parser is made and how it integrates with the Zenroom memory model. It serves as a reference documentation on functions used to write parsers for new Zencode scenarios in Zenroom's Lua.

Info:

  • Copyright: Dyne.org foundation 2018-2019
  • License: AGPLv3
  • Author: Denis "Jaromil" Roio

Given block (IN read-only memory)

Iam (name) Declare 'my own' name that will refer all uses of the 'my' pronoun to structures contained under this name.
pick (name, data) Pick a generic data structure from the IN memory space.
pickin (section, name) Pick a data structure named 'what' contained under a 'section' key of the at the root of the IN memory space.
validate (name, schema) Optional step inside the Given block to execute schema validation on the last data structure selected by pick.
ack (name) Final step inside the Given block towards the When: pass on a data structure into the ACK memory space, ready for processing.

When block (ACK read-write memory)

draft (string) Draft a new text made of a simple string: convert it to OCTET and append it to ACK.draft.
eq () Compare equality of two data objects (TODO: octet, ECP, etc.)
gt () Check that the first object is greater than the second (TODO)
lt () Check that the first object is lesser than the second (TODO)

Then block (OUT write-only memory)

out () Move a generic data structure from ACK to OUT memory space, ready for its final JSON encoding and print out.
outmy () Move 'my own' data structure from ACK to OUT.whoami memory space, ready for its final JSON encoding and print out.
export (object, format) Convert a data object to the desired format (argument name provided as string), or use CONF.encoding when called without argument
import (object) Import a generic data element from the tagged format, or use CONF.encoding
zencode:begin (verbosity) ZENCODE PARSER


Given block (IN read-only memory)

Iam (name)
Declare 'my own' name that will refer all uses of the 'my' pronoun to structures contained under this name. (name)

Parameters:

  • name own name to be saved in ACK.whoami
pick (name, data)
Pick a generic data structure from the IN memory space. Looks for named data on the first and second level and makes it ready for validate or ack. (name, data)

Parameters:

  • name string descriptor of the data object
  • data [opt] optional data object (default search inside IN.*)

Returns:

    true or false
pickin (section, name)
Pick a data structure named 'what' contained under a 'section' key of the at the root of the IN memory space. Looks for named data at the first and second level underneath IN[section] and moves it to TMP[what][section], ready for validate or ack. If TMP[what] exists already, every new entry is added as a key/value (section, name)

Parameters:

  • section string descriptor of the section containing the data
  • name string descriptor of the data object

Returns:

    true or false
validate (name, schema)
Optional step inside the Given block to execute schema validation on the last data structure selected by pick. (name)

Parameters:

  • name string descriptor of the data object
  • schema [opt] string descriptor of the schema to validate

Returns:

    true or false
ack (name)
Final step inside the Given block towards the When: pass on a data structure into the ACK memory space, ready for processing. It requires the data to be present in TMP[name] and typically follows a pick. In some restricted cases it is used inside a When block following the inline insertion of data from zencode. (name)

Parameters:

  • name string key of the data object in TMP[name]

When block (ACK read-write memory)

draft (string)
Draft a new text made of a simple string: convert it to OCTET and append it to ACK.draft. (string)

Parameters:

  • string any string to be appended as draft
eq ()
Compare equality of two data objects (TODO: octet, ECP, etc.) (first, second)
gt ()
Check that the first object is greater than the second (TODO) (first, second)
lt ()
Check that the first object is lesser than the second (TODO) (first, second)

Then block (OUT write-only memory)

out ()
Move a generic data structure from ACK to OUT memory space, ready for its final JSON encoding and print out. (name)
outmy ()
Move 'my own' data structure from ACK to OUT.whoami memory space, ready for its final JSON encoding and print out. (name)
export (object, format)
Convert a data object to the desired format (argument name provided as string), or use CONF.encoding when called without argument (object, format)

Parameters:

  • object data element to be converted
  • format pointer to a converter function

Returns:

    object converted to format
import (object)
Import a generic data element from the tagged format, or use CONF.encoding (object)

Parameters:

  • object data element to be read

Returns:

    object read
zencode:begin (verbosity)
ZENCODE PARSER

Parameters:

  • verbosity
generated by LDoc 1.4.3 Last updated 2019-10-01 10:18:34
]==]