uson
v0.3.5
Published
μson (uson) is a shorthand for JSON
Downloads
64
Readme
μ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
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
- stringint
- integerfloat
- floatnull
- nullbool
- booleandate
- 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
- 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
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ý <[email protected]>
Licence
MIT