JML Tools

This library is aimed at providing a set of tools to work with XML-based markup JSON data similar to (but not the same as) JSON-ML in JavaScript. The "markup language" (JML) is defined by the non-compact JSON structure proposed by the xml-js library. It can be converted lossless to and from XML documents including mixed-content elements. The tools are fully namespace aware.

Usage

Installation

npm install jml-tools --save

or

yarn add jml-tools

Quick start

import {create} from 'jml-tools';
const name = 'person';
const data = {content: 'Freddie Mercury'};
const jmlObject = create(name, data);
console.log(jmlObject);
 
// Output:
// {
//     "elements": [
//         {
//             "elements": [
//                 {
//                     "text": "Freddie Mercury",
//                     "type": "text"
//                 }
//             ],
//             "name": "person",
//             "type": "element"
//         }
//     ]
// }

Running tests

npm test

API Reference

This library provides the following functionalities:

create

Manually creates a JML object that is fully compatible with xml-js.

Syntax

create(name[, data])

Parameters

name

A string, either prefixed or not that will be the name of the object to be created.

data

An optional data object that can have any or all of the following properties:

Usage example

import {create} from 'jml-tools';
const name = 'person';
const data = {content: 'Freddie Mercury'};
const jmlObject = create(name, data);
console.log(jmlObject);
 
// Output:
// {
//     "elements": [
//         {
//             "elements": [
//                 {
//                     "text": "Freddie Mercury",
//                     "type": "text"
//                 }
//             ],
//             "name": "person",
//             "type": "element"
//         }
//     ]
// }

evaluate

Evaluates a path expression similar to XPath on a JML object starting with the content of the root object. It doesn't support all of the functionalities of XPath, most importantly, while the descendant axis is available in the form of the double forward slash //, the other axes are not.

Syntax

evaluate(path, jmlObject[, options])

Parameters

path

A string that describes the individual steps that form the path to evaluate on a JML object. The steps are made up of (optionally qualified) object names, text() to select text content or @name to select an object attribute. Each step can have zero or more conditions that describe which specific objects it will match.

Examples

Notable differences to XPath

• The value of an attribute can be accessed directly by /something/@attribute instead of data(/something/@attribute) or /something/@attribute/string()
• When evaluating on an object that is equivalent to <persons><person><name><given>Freddy</given></name></person><person><name><given>Brian</given></name></person></persons>, //given[1] returns the first of all given objects, wherever they appear, instead of the first given object in each individual context like in XPath. A functionality similar to the default in XPath behaviour can be achieved by //name/given[1].

jmlObject

A valid JML object as created by the create method and xml-js. The path will be evaluated on its contents starting inside the root object.

options

An optional object that describes the options for the evaluation:

Usage example

import {evaluate} from 'jml-tools';
// original XML:
// <paragraph xmlns="http://example.com/ns">JSON is just as <emphasized>fun</emphasized> as XML.</paragraph>
const jmlObject = {
    elements: [{
        type: 'element',
        name: 'paragraph',
        attributes: {
            xmlns: 'http://example.com/ns'
        },
        elements: [
            {type: 'text', text: 'JSON is just as '},
            {
                type: 'element',
                name: 'emphasized',
                elements: [
                    {type: 'text', text: 'fun'}
                ]
            },
            {type: 'text', text: ' as XML.'}
        ]
    }]
};
const result = evaluate('/ns:emphasized/text()', jmlObject, {namespaces: [{prefix: 'ns', uri: 'http://example.com/ns'}]});
console.log(result);
 
// Output:
// ['fun']

serialize

Serializes a JML object to a string according to fully qualified mappings that target either the whole object or individual child objects. This can, for example, be used to transform arbitrary structures into HTML or a different JSON representation.

Syntax

serialize(jmlObject, mappings[, options])

Parameters

jmlObject

A valid JML object as created by the create method and xml-js. It will be serialized according to the provided mappings.

mappings

The rules to apply to the jmlObject. It describes how its contents will be serialized. It can any of the following:

1. An object consisting of string key-value pairs describing the mapping into serialized XML. An asterisk (*) as key is interpreted as the default mapping to use if no other mapping matches.
2. An object consisting of key-key value pairs similar to option 1 above with the difference that the value is not a string but a function that should return the transformed content as a string. The functions' signature is function({name, contents, attributes}).
3. A function that will be applied to each child object (similar to the child elements in XML). The functions' signature is function({name, contents, attributes}).

Note 1: The options 1 and 2 can be mixed with each other. It is possible to map some keys to string values and some to functions.

Note 2: If the object to be match by options 1 and 2 above are qualified, the objects' namespace needs to be declared in the options object and the correct prefixes need to be added to the keys to match the specific objects.

options

An optional object that describes the options for the serialization:

Usage example

import {serialize} from 'jml-tools';
// original XML:
// <paragraph xmlns="http://example.com/ns">JSON is just as <emphasized>fun</emphasized> as XML.</paragraph>
const jmlObject = {
    elements: [{
        type: 'element',
        name: 'paragraph',
        attributes: {
            xmlns: 'http://example.com/ns'
        },
        elements: [
            {type: 'text', text: 'JSON is just as '},
            {
                type: 'element',
                name: 'emphasized',
                elements: [
                    {type: 'text', text: 'fun'}
                ]
            },
            {type: 'text', text: ' as XML.'}
        ]
    }]
};
const mappings = {
    'ns:paragraph': 'p',
    'ns:emphasized': 'i'
};
const options = {
    namespaces: [{
        prefix: 'ns',
        uri: 'http://example.com/ns'
    }]
};
const serialized = serialize(jmlObject, mappings, options);
console.log(serialized);
 
// Output:
// <p>JSON is just as <i>fun</i> as XML.</p>

Authors

• Daniel Jeller

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Thanks to @nashwaan for his excellent xml-js library.