{"id":13623883,"url":"https://github.com/burningtree/uson","last_synced_at":"2025-04-24T18:33:36.043Z","repository":{"id":29913402,"uuid":"33459252","full_name":"burningtree/uson","owner":"burningtree","description":"μson (uson) is a shorthand for JSON","archived":false,"fork":false,"pushed_at":"2022-12-30T18:29:12.000Z","size":471,"stargazers_count":78,"open_issues_count":12,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-02T00:04:22.562Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/burningtree.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-05T23:53:05.000Z","updated_at":"2024-07-13T06:08:34.000Z","dependencies_parsed_at":"2023-01-14T15:54:08.485Z","dependency_job_id":null,"html_url":"https://github.com/burningtree/uson","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burningtree%2Fuson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burningtree%2Fuson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burningtree%2Fuson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burningtree%2Fuson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/burningtree","download_url":"https://codeload.github.com/burningtree/uson/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223684841,"owners_count":17185721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:01:36.622Z","updated_at":"2024-11-08T12:30:29.374Z","avatar_url":"https://github.com/burningtree.png","language":"JavaScript","readme":"# μson (uson)\n\n[![Build Status](https://travis-ci.org/burningtree/uson.svg?branch=master)](https://travis-ci.org/burningtree/uson) [![Dependency Status](https://david-dm.org/burningtree/uson.svg)](https://david-dm.org/burningtree/uson) [![npm](https://img.shields.io/npm/v/uson.svg)](https://www.npmjs.com/package/uson)\n\nA compact human-readable data serialization format specially designed for shell.\n\nThis format is certainly not intended to replace the classical JSON format, but brings different syntax, for use in environments with specific requirements.\n\nMain 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.\n\nThis 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).\n\n* [μson Overview](#%CE%BCson-overview)\n* [Node.js module](#nodejs-module)\n* [Browser usage](#browser-usage)\n* [Command-line tool (CLI)](#command-line-tool-cli)\n\n## μson Overview\n\n* [Introduction](#introduction)\n  * [Principles](#principles)\n  * [Output modes](#output-modes)\n* [Example](#example)\n* [Basic usage](#basic-usage)\n  * [Standard types](#standard-types)\n  * [Arrays](#arrays)\n  * [Objects](#objects)\n  * [Nested objects](#nested-objects)\n  * [Type casting](#type-casting)\n  * [Custom types](#custom-types)\n  * [Comments](#comments)\n* [Grammar](#grammar)\n\n### Introduction\n\n#### Principles\n\n* Superset of JSON (every JSON is valid μson).\n* Whitespace is not significant.\n* String quoting `\"` is optional.\n* In Array or Object, comma `,` can be replaced by whitespace ` `.\n* Assignation with colon `:` can be repeated to create nested objects. (see [Nested objects](#nested-objects)).\n* You can use own types, casting is done by `!` character. (see [Type casting](#type-casting)).\n\n#### Output modes\n\nThere are three output modes:\n* `array` (default) - Output as array.\n* `object` - Output as combined object. Suitable for use in the command line.\n* `json` - Output first mixed type. 100% compatible with JSON.\n\n### Example\n\n```\nendpoint:id:wikipedia pages:[Malta Prague \"New York\"]\n```\n\nResult in JSON (`array` mode):\n```json\n[\n  {\n    \"endpoint\": {\n      \"id\": \"wikipedia\"\n    }\n  },\n  {\n    \"pages\": [\n      \"Malta\",\n      \"Prague\",\n      \"New York\"\n    ]\n  }\n]\n```\n\nor in YAML (`array` mode):\n```yaml\n- endpoint:\n    id: wikipedia\n- pages:\n    - Malta\n    - Prague\n    - New York\n```\n\nand `object` mode result:\n```json\n{\n  \"endpoint\": {\n    \"id\": \"wikipedia\"\n  },\n  \"pages\": [\n    \"Malta\",\n    \"Prague\",\n    \"New York\"\n  ]\n}\n```\n\n### Basic usage\n\n```\nexpr1 expr2 expr3 ..\n```\n\nSupported types:\n* false\n* null\n* true\n* array\n* object\n* number\n* string\n\nOptional:\n* regexp TODO\n* function TODO\n\n#### Standard types\n\n```\nnumber:12.05 text:Banana quotedText:\"John Devilseed\" empty:null good:true\n```\n\nOutput in `object` mode:\n```json\n{\n  \"number\": 12.05,\n  \"text\": \"Banana\",\n  \"quotedText\": \"John Devilseed\",\n  \"empty\": null,\n  \"good\": true\n}\n```\n\n#### Arrays\n\n```\nsimple:[1 2 3] texts:[Malta Budapest \"New York\"] objects:[{id:1}]\n```\n\nOutput in `object` mode:\n```json\n{\n  \"simple\": [\n    1,\n    2,\n    3\n  ],\n  \"texts\": [\n    \"Malta\",\n    \"Budapest\",\n    \"New York\"\n  ],\n  \"objects\": [\n    {\n      \"id\": 1\n    }\n  ]\n}\n```\n\n#### Objects\n\n```\nobj:{name:John} {nested:[{id:42} value:\"Nagano\"]}\n```\n\nOutput in `object` mode:\n```json\n{\n  \"obj\": {\n    \"name\": \"John\"\n  },\n  \"nested\": [\n    {\n      \"id\": 42\n    },\n    {\n      \"value\": \"Nagano\"\n    }\n  ]\n}\n```\n\n#### Nested objects\n\nYou can use standard colon notation for expand objects:\n```\n\u003ckey\u003e:(\u003cvalue\u003e|(\u003ckey\u003e:(\u003cvalue\u003e| .. )))\n```\n\nFor example:\n```\ncities:eu:hu:budapest:Budapest\n```\n\nbecome:\n```json\n[\n  {\n    \"cities\": {\n      \"eu\": {\n        \"hu\": {\n          \"budapest\": \"Budapest\"\n        }\n      }\n    }\n  }\n]\n```\n\n#### Type casting\n\nIf you want to return a value in specific type, you can use this syntax:\n```\n\u003ctype\u003e!\u003cexpr\u003e\n```\n\nFor example, this input:\n```\nstr!42\n```\n\nproduce this output:\n```\n[\"42\"]\n```\n\nYou can use casting repeatedly:\n```\nstr!int!12.42\n```\n\noutput:\n```\n[\"12\"]\n```\n\nThis could be useful especially if you define your [own types](#custom-types).\n\n##### Core casting types\n\n**Scalars:**\n* `str` - string\n* `int` - integer\n* `float` - float\n* `null` - null\n* `bool` - boolean\n* `date` - date \u0026 time (ISO 8601 formatting)\n\n#### Custom types\n\nIf 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).\n\nFor CLI you can create `.usonrc.js` file in your home directory `~/`, in which you can define your own types. See [Configuration](#configuration).\n\n#### Comments\n\nComments beginning with `#` and terminates on end of line.\n\n```\narray:[1 2 3] # this is comment\n```\n\nOutput:\n```json\n{\n  \"array\": [\n    1,\n    2,\n    3\n  ]\n}\n```\n\n### Grammar\n\nBasic grammar is adopted from JSON:\n\n```\nbegin_array     = ws \"[\" ws\nbegin_object    = ws \"{\" ws\nend_array       = ws \"]\" ws\nend_object      = ws \"}\" ws\nname_separator  = ws \":\" ws\nvalue_separator = ws [ ,]* ws\ncomment_start   = \"#\"\nws_char         = [ \\t\\n\\r]\n```\n\nFor more info see [uson.pegjs](src/uson.pegjs) file.\n\n[Visualization of uson grammar](http://dundalek.com/GrammKit/#https://raw.githubusercontent.com/burningtree/uson/master/src/uson.pegjs).\n\n## Node.js module\n\n* [Compatibility](#compatibility)\n* [Installation](#installation)\n* [Usage](#usage)\n* [Defining own types](#defining-own-types)\n\n### Compatibility\n\n* node.js 0.10+\n* [io.js](https://iojs.org) v1.0.4+\n\n### Installation\n\n```\n$ npm install uson\n```\n\n### Usage\n\nAPI is almost same as JSON API:\n* `USON.parse(str, mode=\"object\", customTypes={})`\n* `USON.stringify(obj, replacer=null, level=2)` - in development\n\n```javascript\nvar USON = require('uson');\nconsole.log(USON.parse('a b c'));\n```\nOutput:\n```javascript\n[ 'a', 'b', 'c' ]\n```\n\n### Defining own types\n\n```javascript\nvar USON = require('uson');\nvar types = {\n  welcome: function(value) {\n    return(\"Hello \" + value + \"!\");\n  }\n};\nconsole.log(USON.parse('welcome!john', null, types));\n```\nOutput:\n```javascript\n[ 'Hello john!' ]\n```\n\n## Browser usage\n\n```\n$ bower install uson\n```\n\n### Usage\n\n```html\n  \u003cscript src=\"bower_components/uson/dist/uson.min.js\"\u003e\u003c/script\u003e\n  \u003cscript\u003e\n    var output = USON.pack('a b c');\n    console.log(output);\n  \u003c/script\u003e\n```\n\n## Command-line tool (CLI)\n\n* [Installation](#installation-1)\n* [Usage](#usage-2)\n* [Example](#example-1)\n* [Options](#options)\n  * [Result format (optional)](#result-format-optional)\n* [Streams support (pipe)](#streams-support-pipe)\n* [Complete usage](#complete-usage)\n\n\n### Installation\n\nYou can install node.js CLI utility via npm:\n```\n$ npm install -g uson\n```\n\n### Usage\n\n```\n$ uson [options] [expression]\n```\n\n### Example\n\n```\n$ uson 'user:john age:42'\n```\n\nReturn:\n```json\n[{\"user\":\"john\"},{\"age\":42}]\n```\n\n### Options\n\nFor `object` mode use option `-o, --object`.\n\nFor `json` mode use option `-j, --json`.\n\nIf you want prettyfied output, use option `-p, --pretty`.\n\n#### Result format\n\nYou can use this output formats:\n- JSON (default): `-j, --json`\n- [Query string](http://en.wikipedia.org/wiki/Query_string): `-f, --form` (optional)\n- [YAML](http://yaml.org): `-y, --yaml` (optional)\n- [MessagePack](http://msgpack.org/): `-m, --msgpack` (optional)\n\nFor example, this returns YAML in Object mode:\n```\n$ uson -yo 'endpoint:id:wikipedia'\n```\n\nReturn:\n```yaml\nendpoint:\n  id: wikipedia\n```\n\n### Configuration\n\n#### `.usonrc.js` file\n\nYou 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.\n\nRC file is normal Javascript (Node.js) script. Output must be stored in `module.exports` variable.\n\n##### Example `.usonrc.js`\n\n```javascript\nvar chance = require('chance')();\n\nmodule.exports = {\n  types: {\n    g: function(val) {\n      var args = [];\n      var cmd = null;\n      if(typeof val == \"object\") {\n        cmd = Object.keys(val)[0];\n        args = val[cmd];\n      } else {\n        cmd = val;\n      }\n      return chance[cmd] ? chance[cmd](args) : null;\n    },\n    js: function(js) {\n      return eval(js);\n    },\n    'hello': function(val) {\n      return 'Hello '+ val;\n    }\n  }\n}\n```\n\nWith this example RC file you can generate random values (with excellent [Chance](http://chancejs.com) library), execute Javascript code or simple say hello:\n\n```\n$ uson -op 'calc:js!\"36+64\" name:g!name ip:g!ip welcome:hello!Mark'\n```\n\nAnd this is result in `object` mode:\n\n```json\n{\n  \"calc\": 100,\n  \"name\": \"Jeffrey Mendez\",\n  \"ip\": \"237.63.92.106\",\n  \"welcome\": \"Hello Mark\"\n}\n```\n\n### Streams support (pipe)\n\nIf you dont specify any input or options then input is taken from standard input (stdin). This can be used for \"piping\" results:\n\n```\n$ echo \"a b c:[a:42]\" | uson | jq .[2].c[0].a\n```\nResult:\n\n```json\n42\n```\n\n### Complete usage\n\n```\n$ uson --h\n\n  Usage: uson [options] [expression]\n\n  μson (uson) is a shorthand for JSON\n\n  Options:\n\n    -h, --help             output usage information\n    -V, --version          output the version number\n    -o, --object           \"object\" mode\n    -j, --json             \"json\" mode\n    -i, --input \u003cfile\u003e     Load data from file\n        --output \u003cfile\u003e    Write output to file\n    -p, --pretty           Pretty print output (only JSON)\n    -f, --form             Return output in form query-string\n    -y, --yaml             Return output in YAML (optional)\n    -m, --msgpack          Return output in msgpack (optional)\n    -u, --usonrc \u003cusonrc\u003e  Use \u003cusonrc\u003e instead of any .usonrc.js\n        --hex              Output in hex encoding\n        --base64           Output in base64 encoding\n\n```\n\n## NPM package stats\n[![NPM](https://nodei.co/npm/uson.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/uson/)\n\n## Inspiration\nInspired by python CLI utility [jarg](https://github.com/jdp/jarg) by Justin Poliey ([@jdp](https://github.com/jdp)).\n\n## Author\nJan Stránský \u0026lt;jan.stransky@arnal.cz\u0026gt;\n\n## Licence\nMIT\n\n","funding_links":[],"categories":["Supersets","What's Next?","JavaScript"],"sub_categories":["USON"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburningtree%2Fuson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fburningtree%2Fuson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburningtree%2Fuson/lists"}