Yet Another Simple Object Notation (YASON)

YASON is a small superset of JSON, compatible with the YAML language. It extends JSON with support for (circular) references and typing (YAML tags).

This project was created as a support project for other projects and YASON strings should be easily filterable by line-based filtering tools (e.g. grep). Therefore YASON generators should not generate newlines by default, although they are supported.

YASON is JSON with the following YAML-compatible changes:

• References: A referencable element can be defined by putting &refname in front of it and by using *refname to refer to it.
• Classes/Types/Namespaces: Elements can be classified using YAML-compatible tags (!tag, !!tag). A tag is defined as an exclamation mark followed by a sequence of non-whitespace characters. The tag ends with a whitespace character.
• By default no newlines at generation time, although newlines are supported by the parser, they should not be generated by the generator

A YASON stream is a sequence of YASON values. Two values are separated by a newline and any number of whitespaces.

Basic Usage

To serialize a single object, simply use the stringify method:

var YASON = require("yason");
var obj = {
  test: [1, "b", {cde: "fgh"}],
  another_test: {another_key: "another value"}
};
obj["circular-reference"] = obj;
obj["test"].push(obj["another_test"]);
console.log(YASON.stringify(obj));

To deserialize a single object, use the parse method:

var YASON = require("yason");
var str = '&root { lirum: "larum", "asdf": ["1", 2, "three", ' +
  '&ref0 {four: "5"}], root: *root, "refer to ref0": *ref0}';
console.log(YASON.parse(str));

Usage / API

Use const YASON = require('yason'); to include the YASON module in your nodejs application. The YASON object will then contain the following items:

• Generator: YASON generator (serializer) class.
• Parser: YASON parser (deserializer) class.
• GeneratorTransform: A nodejs transform stream that transforms JavaScript values into YASON strings.
• ParserTransform: A nodejs transform stream that transforms YASON strings (or Buffers) into JavaScript values. Since streams don't support writing null values, they can't be serialized using this transform.
• stringify: Function that serializes a JavaScript value into a YASON string.
• parse: Function that deserializes a YASON string into a JavaScript value.

YASON.stringify(value, options)

Converts the value (object, array, number, string, boolean, null) into a YASON string. The method supports the following options:

• classifier: A function with the signature classifier(value, container) that returns the class (tag) that should be used for the value. The tag must not contain any whitespaces (including newlines). A "!" will be prepended automatically. If null is returned, no tag will be used for the value. value is the value that will be serialized next, container is the object or array that contains the value (or null).

YASON.parse(string)

Parses a YASON string and converts it to the corresponding value. The result may contain values of type YasonTaggedValue. Tagged values are values of the YASON string that were tagged with a !tag, e.g. because the classifier of the stringify method returned a non-null value.

Generator

The generator serializes JavaScript values into YASON strings.

var generator = new YASON.Generator(options)

Creates a new YASON generator object. Valid options are:

• classifier: The classifier that should be used for the stringify(...) method. If stringify(...) is called with a different classifier option, that option will override the constructor option.
• stringReferences: Options for string references. If the same string appears more than once, further appearances may be replaced with a *referenceId and the first appearance will be turned into a &referenceId reference definition. This is only done if some conditions are met, for now the only condition is the string length. ** stringReferences.minimumLength: Strings are only turned into references if the are at least minimumLength characters long.

generator.stringify(value, options)

See descriptions of YASON.stringify(value, options)

Parser

const Parser = YASON.Parser

The parser is a class with a single class-method Parser.parse(string).

Parser.parse(string)

Parses a string and converts it into a JavaScript value.

GeneratorTransform

A nodejs Transform that converts JavaScript values into YASON strings. It puts a newline after each serialized value.

var trans = new YASON.GeneratorTransform(options)

Create a new generator Transform object. The options parameter can contain the following settings:

• generator: Options that will be passed through to the YASON.Generator constructor. See the description of the Generator constructor for more information.

You can use the Transform like any other nodejs Transform, e.g. pipe it to stdout:

var YasonGeneratorTransform = require("yason").GeneratorTransform;

var out = new YasonGeneratorTransform();
out.pipe(process.stdout);

out.write({lirum: "larum"});
out.write({bla: ["ble", "blu", "larum"], 1: [2, {3: 4}]});

ParserTransform

A nodejs Transform that converts YASON strings (Buffers) into JavaScript values. Values are seperated by any number of whitespaces of which at least one is a newline.

var trans = new YASON.ParserTransform(options)

Creates a new parser Transform object. Currently no options are supported. The transform can be used like any other nodejs Transform:

var YasonParserTransform = require("yason");

var input = new YasonParserTransform();
input.on("data", (data) => {
  console.log("data: ", data);
});

process.stdin.pipe(input);
input.resume();