Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/burningtree/uson
μson (uson) is a shorthand for JSON
https://github.com/burningtree/uson
Last synced: about 1 month ago
JSON representation
μson (uson) is a shorthand for JSON
- Host: GitHub
- URL: https://github.com/burningtree/uson
- Owner: burningtree
- License: mit
- Created: 2015-04-05T23:53:05.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-30T18:29:12.000Z (almost 2 years ago)
- Last Synced: 2024-11-02T00:04:22.562Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 460 KB
- Stars: 78
- Watchers: 4
- Forks: 2
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-repos - burningtree/uson - μson (uson) is a shorthand for JSON (JavaScript)
- awesome-json - μson - a shorthand for JSON. (Supersets)
- awesome-json-next - burningtree/uson
README
# μson (uson)
[](https://travis-ci.org/burningtree/uson) [](https://david-dm.org/burningtree/uson) [](https://www.npmjs.com/package/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](http://en.wikipedia.org/wiki/Parsing_expression_grammar) and parser is generated by [peg.js](http://pegjs.org/). For more info see [Grammar](#grammar).
* [μson Overview](#%CE%BCson-overview)
* [Node.js module](#nodejs-module)
* [Browser usage](#browser-usage)
* [Command-line tool (CLI)](#command-line-tool-cli)
## μson Overview
* [Introduction](#introduction)
* [Principles](#principles)
* [Output modes](#output-modes)
* [Example](#example)
* [Basic usage](#basic-usage)
* [Standard types](#standard-types)
* [Arrays](#arrays)
* [Objects](#objects)
* [Nested objects](#nested-objects)
* [Type casting](#type-casting)
* [Custom types](#custom-types)
* [Comments](#comments)
* [Grammar](#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](#nested-objects)).
* You can use own types, casting is done by `!` character. (see [Type casting](#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):
```json
[
{
"endpoint": {
"id": "wikipedia"
}
},
{
"pages": [
"Malta",
"Prague",
"New York"
]
}
]
```
or in YAML (`array` mode):
```yaml
- endpoint:
id: wikipedia
- pages:
- Malta
- Prague
- New York
```
and `object` mode result:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"obj": {
"name": "John"
},
"nested": [
{
"id": 42
},
{
"value": "Nagano"
}
]
}
```
#### Nested objects
You can use standard colon notation for expand objects:
```
:(|(:(| .. )))
```
For example:
```
cities:eu:hu:budapest:Budapest
```
become:
```json
[
{
"cities": {
"eu": {
"hu": {
"budapest": "Budapest"
}
}
}
}
]
```
#### Type casting
If you want to return a value in specific type, you can use this syntax:
```
!
```
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](#custom-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](#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](#configuration).
#### Comments
Comments beginning with `#` and terminates on end of line.
```
array:[1 2 3] # this is comment
```
Output:
```json
{
"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](src/uson.pegjs) file.
[Visualization of uson grammar](http://dundalek.com/GrammKit/#https://raw.githubusercontent.com/burningtree/uson/master/src/uson.pegjs).
## Node.js module
* [Compatibility](#compatibility)
* [Installation](#installation)
* [Usage](#usage)
* [Defining own types](#defining-own-types)
### Compatibility
* node.js 0.10+
* [io.js](https://iojs.org) 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
```javascript
var USON = require('uson');
console.log(USON.parse('a b c'));
```
Output:
```javascript
[ 'a', 'b', 'c' ]
```
### Defining own types
```javascript
var USON = require('uson');
var types = {
welcome: function(value) {
return("Hello " + value + "!");
}
};
console.log(USON.parse('welcome!john', null, types));
```
Output:
```javascript
[ 'Hello john!' ]
```
## Browser usage
```
$ bower install uson
```
### Usage
```html
var output = USON.pack('a b c');
console.log(output);
```
## Command-line tool (CLI)
* [Installation](#installation-1)
* [Usage](#usage-2)
* [Example](#example-1)
* [Options](#options)
* [Result format (optional)](#result-format-optional)
* [Streams support (pipe)](#streams-support-pipe)
* [Complete usage](#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:
```json
[{"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](http://en.wikipedia.org/wiki/Query_string): `-f, --form` (optional)
- [YAML](http://yaml.org): `-y, --yaml` (optional)
- [MessagePack](http://msgpack.org/): `-m, --msgpack` (optional)
For example, this returns YAML in Object mode:
```
$ uson -yo 'endpoint:id:wikipedia'
```
Return:
```yaml
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`
```javascript
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](http://chancejs.com) 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:
```json
{
"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:
```json
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 Load data from file
--output 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 Use instead of any .usonrc.js
--hex Output in hex encoding
--base64 Output in base64 encoding
```
## NPM package stats
[](https://nodei.co/npm/uson/)
## Inspiration
Inspired by python CLI utility [jarg](https://github.com/jdp/jarg) by Justin Poliey ([@jdp](https://github.com/jdp)).
## Author
Jan Stránský <[email protected]>
## Licence
MIT