uson

μson (uson)

A compact human-readable data serialization format specially designed for shell.

This format is certainly not intended to replace the classical JSON format, but brings different syntax, for use in environments with specific requirements.

Main advantage should be in better writability (mostly in the command line), because use less expressive syntax. The purpose is not to create a format that is as small as possible in term of byte size.

This is initial implementation written in Javascript and node.js. Grammar is written in PEG and parser is generated by peg.js. For more info see Grammar.

• μson Overview
• Node.js module
• Browser usage
• Command-line tool (CLI)

μson Overview

• Introduction
  • Principles
  • Output modes
• Example
• Basic usage
  • Standard types
  • Arrays
  • Objects
  • Nested objects
  • Type casting
  • Custom types
  • Comments
• Grammar

Introduction

Principles

• Superset of JSON (every JSON is valid μson).
• Whitespace is not significant.
• String quoting " is optional.
• In Array or Object, comma , can be replaced by whitespace .
• Assignation with colon : can be repeated to create nested objects. (see Nested objects).
• You can use own types, casting is done by ! character. (see Type casting).

Output modes

There are three output modes:

• array (default) - Output as array.
• object - Output as combined object. Suitable for use in the command line.
• json - Output first mixed type. 100% compatible with JSON.

Example

endpoint:id:wikipedia pages:[Malta Prague "New York"]

Result in JSON (array mode):

[
  {
    "endpoint": {
      "id": "wikipedia"
    }
  },
  {
    "pages": [
      "Malta",
      "Prague",
      "New York"
    ]
  }
]

or in YAML (array mode):

- endpoint:
    id: wikipedia
- pages:
    - Malta
    - Prague
    - New York

and object mode result:

{
  "endpoint": {
    "id": "wikipedia"
  },
  "pages": [
    "Malta",
    "Prague",
    "New York"
  ]
}

Basic usage

expr1 expr2 expr3 ..

Supported types:

• false
• null
• true
• array
• object
• number
• string

Optional:

• regexp TODO
• function TODO

Standard types

number:12.05 text:Banana quotedText:"John Devilseed" empty:null good:true

Output in object mode:

{
  "number": 12.05,
  "text": "Banana",
  "quotedText": "John Devilseed",
  "empty": null,
  "good": true
}

Arrays

simple:[1 2 3] texts:[Malta Budapest "New York"] objects:[{id:1}]

Output in object mode:

{
  "simple": [
    1,
    2,
    3
  ],
  "texts": [
    "Malta",
    "Budapest",
    "New York"
  ],
  "objects": [
    {
      "id": 1
    }
  ]
}

Objects

obj:{name:John} {nested:[{id:42} value:"Nagano"]}

Output in object mode:

{
  "obj": {
    "name": "John"
  },
  "nested": [
    {
      "id": 42
    },
    {
      "value": "Nagano"
    }
  ]
}

Nested objects

You can use standard colon notation for expand objects:

<key>:(<value>|(<key>:(<value>| .. )))

For example:

cities:eu:hu:budapest:Budapest

become:

[
  {
    "cities": {
      "eu": {
        "hu": {
          "budapest": "Budapest"
        }
      }
    }
  }
]

Type casting

If you want to return a value in specific type, you can use this syntax:

<type>!<expr>

For example, this input:

str!42

produce this output:

["42"]

You can use casting repeatedly:

str!int!12.42

output:

["12"]

This could be useful especially if you define your own types.

Core casting types

Scalars:

• str - string
• int - integer
• float - float
• null - null
• bool - boolean
• date - date & time (ISO 8601 formatting)

Custom types

If you use library, it's easy to add support for your own types - just pass object with types as third argument to parse(). See Defining own types.

For CLI you can create .usonrc.js file in your home directory ~/, in which you can define your own types. See Configuration.

Comments

Comments beginning with # and terminates on end of line.

array:[1 2 3] # this is comment

Output:

{
  "array": [
    1,
    2,
    3
  ]
}

Grammar

Basic grammar is adopted from JSON:

begin_array     = ws "[" ws
begin_object    = ws "{" ws
end_array       = ws "]" ws
end_object      = ws "}" ws
name_separator  = ws ":" ws
value_separator = ws [ ,]* ws
comment_start   = "#"
ws_char         = [ \t\n\r]

For more info see uson.pegjs file.

Visualization of uson grammar.

Node.js module

• Compatibility
• Installation
• Usage
• Defining own types

Compatibility

• node.js 0.10+
• io.js v1.0.4+

Installation

$ npm install uson

Usage

API is almost same as JSON API:

• USON.parse(str, mode="object", customTypes={})
• USON.stringify(obj, replacer=null, level=2) - in development

var USON = require('uson');
console.log(USON.parse('a b c'));

Output:

[ 'a', 'b', 'c' ]

Defining own types

var USON = require('uson');
var types = {
  welcome: function(value) {
    return("Hello " + value + "!");
  }
};
console.log(USON.parse('welcome!john', null, types));

Output:

[ 'Hello john!' ]

Browser usage

$ bower install uson

Usage

  <script src="bower_components/uson/dist/uson.min.js"></script> 
  <script>
    var output = USON.pack('a b c');
    console.log(output);
  </script> 

Command-line tool (CLI)

• Installation
• Usage
• Example
• Options
  • Result format (optional)
• Streams support (pipe)
• Complete usage

Installation

You can install node.js CLI utility via npm:

$ npm install -g uson

Usage

$ uson [options] [expression]

Example

$ uson 'user:john age:42'

Return:

[{"user":"john"},{"age":42}]

Options

For object mode use option -o, --object.

For json mode use option -j, --json.

If you want prettyfied output, use option -p, --pretty.

Result format

You can use this output formats:

• JSON (default): -j, --json
• Query string: -f, --form (optional)
• YAML: -y, --yaml (optional)
• MessagePack: -m, --msgpack (optional)

For example, this returns YAML in Object mode:

$ uson -yo 'endpoint:id:wikipedia'

Return:

endpoint:
  id: wikipedia

Configuration

.usonrc.js file

You can create .usonrc.js file in your home directory ~/ which may contain your configuration and which is automatically loaded when cli started. Currently it is only possible to define custom data types.

RC file is normal Javascript (Node.js) script. Output must be stored in module.exports variable.

Example .usonrc.js

var chance = require('chance')();
 
module.exports = {
  types: {
    g: function(val) {
      var args = [];
      var cmd = null;
      if(typeof val == "object") {
        cmd = Object.keys(val)[0];
        args = val[cmd];
      } else {
        cmd = val;
      }
      return chance[cmd] ? chance[cmd](args) : null;
    },
    js: function(js) {
      return eval(js);
    },
    'hello': function(val) {
      return 'Hello '+ val;
    }
  }
}

With this example RC file you can generate random values (with excellent Chance library), execute Javascript code or simple say hello:

$ uson -op 'calc:js!"36+64" name:g!name ip:g!ip welcome:hello!Mark'

And this is result in object mode:

{
  "calc": 100,
  "name": "Jeffrey Mendez",
  "ip": "237.63.92.106",
  "welcome": "Hello Mark"
}

Streams support (pipe)

If you dont specify any input or options then input is taken from standard input (stdin). This can be used for "piping" results:

$ echo "a b c:[a:42]" | uson | jq .[2].c[0].a

Result:

42

Complete usage

$ uson --h

  Usage: uson [options] [expression]

  μson (uson) is a shorthand for JSON

  Options:

    -h, --help             output usage information
    -V, --version          output the version number
    -o, --object           "object" mode
    -j, --json             "json" mode
    -i, --input <file>     Load data from file
        --output <file>    Write output to file
    -p, --pretty           Pretty print output (only JSON)
    -f, --form             Return output in form query-string
    -y, --yaml             Return output in YAML (optional)
    -m, --msgpack          Return output in msgpack (optional)
    -u, --usonrc <usonrc>  Use <usonrc> instead of any .usonrc.js
        --hex              Output in hex encoding
        --base64           Output in base64 encoding

NPM package stats

Inspiration

Inspired by python CLI utility jarg by Justin Poliey (@jdp).

Author

Jan Stránský <[e-mail]>

Licence

MIT