Skip to main content
Version: Next

Serialization/Deserialization

This page defines the basic concepts for the implementation of a parser that serializes/deserializes text in Gura format. In honor of the simplicity of the language, we will try to make this documentation as easy as possible.

Basic types​

All implementations that parse or output text in Gura format must contemplate the following data types to comply with the language specifications:

  • Null: defines a unit value. Different programming languages have different ways of representing this value, for example, in Java, Javascript or PHP it is defined with the type null, in Python it is None, in Ruby it is nil, Option in Rust, and so on. Use the corresponding value depending on which language you are implementing your parser in. Reference.
  • Bool: sets the boolean values that in Gura are defined through the keywords false and true. Reference.
  • String: defines text strings. Regardless of whether they are basic, literal, and/or multiline strings. Reference.
  • Integer: defines signed integers. Reference.
  • Float: defines signed floating-point number. Reference.
  • Array: defines an ordered collection of Gura elements. Reference.
  • Object: defines an ordered structure containing keys that uniquely reference a Gura element. Examples of this type of structure in programming languages are objects in Javascript, a dictionary in Python, a HashMap in Java or Rust, a map in C++, etc. Where the key is a String, and the value is a Gura element that is part of this basic data list. Reference.

It is vitally important to understand that the implementation of a parser is a complex task and will probably involve the use of more complex data structures than the one just mentioned.

These structures should be considered internal and act as utilities to perform certain tasks. For example, the official parsers of Python, Javascript, and Rust (which can be found in the list of implementations) have internal structures to map the indentation, import, variables, among other structures that are only of interest to developers but are not part of the specifications that apply to the end-user. These structures can be freely defined by the tool manager(s) and are not subject to any standard by the Gura team.

Standard errors​

All implementations must consider the following errors (all of them are duly entered in the corresponding sections on the Specs page) during the parsing of Gura text to a representation in the programming language used, to comply with the language specifications:

  • ParseError: Gura syntax is invalid.
  • VariableNotDefinedError: a variable is not defined, or ENV vars are disabled (see Tool parameters section) and a local variable is not found (maybe it is an ENV var, but no check should be made).
  • InvalidIndentationError: indentation is invalid.
  • DuplicatedVariableError: a variable is defined more than once.
  • DuplicatedKeyError: a key is defined more than once.
  • InvalidEscapedCharacterError: an escape sequences not listed in String section is used.
  • FileNotFoundError: an imported file does not exist.
  • DuplicatedImportError: a file is imported more than once.
  • ImportDisabledError: an import sentence is found in Gura file with the import setting disabled (see Tool parameters section).

For all cases, it is recommended that the developing tool provides the line (1-Based indexing, like most IDEs or compilers) and the global position of the text (0-Based indexing, like most IDEs or compilers) where the error occurred. A series of tests (an explanation of this repository is provided below) are provided here to check the correct error reporting.

As mentioned above in the Basic types section, it could be possible that some internal errors may be used during parsing. However, it is reminded that such errors are not part of the formal language specifications and should not be accessible by end-users through the tool API.

Tool parameters​

The parameters to be used during serialization or deserialization functions are up to the developer. However, two parameters are mandatory for all implementations seeking to comply with Gura version 2:

  • Disable imports during serialization: a mechanism must be provided to disable import statements in Gura documents (check the Imports section to learn more). In case this mechanism is disabled, and the document contains an import sentence, an ImportDisabledError error must be thrown. This option should be disabled by default.
  • Disable environment variables serialization: a mechanism must be provided to disable the use of environment variables (check the Variables section to learn more) and only consider variables local to the Gura document (including, if any, imported documents). In case this mechanism is disabled, and a local variable is not found a VariableNotDefinedError error must be thrown. This option should be disabled by default.

Both options ensure security in sensitive environments by preventing access to important system information.

Testing​

A repository containing several tests for validating files with valid Gura format, and all the errors listed above, is made available to developers here.

We encourage all developers to use the tests provided to corroborate the correct functioning of their tools. And to add some tests they consider important during their development (they could be useful for other Gura projects).