really-relaxed-json

Relaxed JSON (RJSON)

See http://www.relaxedjson.org/ for specification and details.

This library is used by the Online RJSON Parser and Formatter.

Quick Usage

Simple conversion from RJSON to compact JSON.

import {toJson} from 'really-relaxed-json'
const rjson = '[ one two three {foo:bar} ]'
const json = toJson(rjson)
// json value is ["one", "two", "three", {"foo": "bar"}]

You can also go the other way, from JSON to RJSON.

import {toRJson} from 'really-relaxed-json'
const json = '["one", "two", "three", {"foo": "bar"}]'
const rjson = toRJson(json)
// rjson value is [ one two three {foo:bar} ]

You can even convert from JSON or RJSON to Javascript.

import {toJs} from 'really-relaxed-json'
const js = toJs('["one", "two", "three", {"foo": "bar"}]')
// js value is ['one', 'two', 'three', {foo: "bar"}]

Simple helper functions are exported by the module.

import {toJson, toRJson, toJs, prettyPrint, Options} from 'really-relaxed-json'

You can also use the full-blown API for more control.

import {api} from 'really-relaxed-json'

Overview

In the spirit of the original JSON, there are only a few simple rules.

• All standard JSON is valid. See json.org for the specification.
• Commas are optional between objects pairs and array items.
• Trailing commas are allowed.
• Quotes are optional around simple-keys and simple-values. We call these Bare Strings.
• Single-quote, double-quote, and backtick quote pairs can be used for strings.
• Multiline strings are allowed.
• Single-line and multi-line comments are allowed.

You can write RJSON like this:
View this example on the Online RJSON Parser and Formatter

{  
 // This is a sample RJSON file  
 buy: [milk eggs butter 'dog bones']  
 tasks: [ {name:exercise completed:false} {name:eat completed:true} ]  
 'another key' : 'another value'  
  /*  It is very easy   
  to read and write RJSON  
 without quotes or commas! */
}  

Convert it to JSON like this:

Simple conversion from RJSON to compact JSON:

import {toJson} from 'really-relaxed-json'
const jsonString = toJson('[ one two three {foo:bar} ]');  

Using a parser object:

var parser = require('really-relaxed-json').createParser();  
var json = parser.stringToValue('[ one two three {foo:bar} ]');  
console.log(json.toString());  
// or  
var jsonString = parser.stringToJson('[ one two three {foo:bar} ]');  
console.log(jsonString);  

Use this library as:

• A pre-processor for ease-of-authoring
• An input/output protocol
• Converting to and from JSON, RJSON, and Javascript
• Pretty printing JSON, RJSON, and Javascript
• Working with a JSON value model

Installation

npm install --save really-relaxed-json  

Node API

The following convenience functions are exported by the Node module

• toJson(rjson:String, compact:Boolean=true) : String
• toRJson(json:String, compact:Boolean=true) : String
• toJs(rjson:String, compact:Boolean=true) : String
• prettyPrint(options:Options, stringOrValue:[String|JsonValue]) : String
• createParser : function
• Options : PrettyPrinter.Options
• api : Object (The full-blown API)

The API also contains classes for formatting and manipulating JSON, RJSON, and Javascript.

Parser Usage

Parser API

import {toJson} from 'really-relaxed-json'
var json = toJson("[one two three {foo:bar} ] /* a comment */");  
console.log(json);  

var parser = require('really-relaxed-json').createParser();
var jsonValue = parser.stringToValue("[one two three {foo:bar} ] /* a comment */");  
// Use toString to print compact JSON, or PrettyPrint it.
console.log(jsonValue.toString());  
  
// Or simply convert directly to a Json string.
// You can feed in either JSON or RJSON with the output always being JSON.
var jsonString = parser.stringToJson("[one two three {foo:bar} ] /* a comment */");  
console.log(jsonString);  

Formatter/Converter Usage

Pretty Printer API

import {prettyPrinter, Options} from 'really-relaxed-json'
var prettyString = prettyPrint(Options.JsonPretty, '[a b c]');  

Using The Options Object

Use one of the presets.

 import {Options} from 'really-relaxed-json'
 var opts;  
  // For JSON
  opts = Options.JsonCompact;  
  opts = Options.JsonPretty;  
  // For RJSON
  opts = Options.RJsonCompact;  
  opts = Options.RJsonPretty;  
  // For Javascript Object
  opts = Options.JsoCompact;  
  opts = Options.JsoPretty;  

Or customize the options.

 var opts = new Options();  
  opts.useQuotes = true;  
  opts.useArrayCommas = true;  
  opts.useObjectCommas = true;  
  opts.objectItemNewline = true;  
  opts.arrayItemNewline = true;  
  opts.isSpaceAfterComma = true;  
  opts.isSpaceAfterColon = true;

API

NPM

The NPM API has a convenience function toJson. It converts RJSON, JSON, or Javascript to a compact or pretty JSON string, perfect
for pipelining.

fun toJson(rjsonString:String, compact:Boolean = true) : String  

Official API Documentation

The Java and Javascript API are the same. http://www.relaxedjson.org/docs/api/

Parser API

Parse API

PrettyPrinter API

Pretty Printer API

JSON Value Model

JSON Value API

Important Changes

Starting with version 0.2.0, we have removed the dependency to Kotlin by embedding a tree-shaken version. The total size is now < 170K for the combined module, including the parser, formatter, utilities, and runtime.

Starting with version 0.2.2, we have added backtick quote support.

Starting with version 0.2.7, you can now convert to and from JavaScript, Json, and RJson.

Starting with version 0.2.9, we have completed replaced our internal parser with one that handles very large files.

Starting with version 0.2.17, we have changed the way the '' character escapes bare strings.

Starting with version 0.2.21, we have added an option to encode unicode characters when PrettyPrinting.

Starting with version 0.2.22, we have added aliases to access Options (bypassing the Companion object).

Starting with version 0.3.0, we have added upgraded to use the latest Kotlin multiplatform conventions. When using in a browser environment, the API is an alias for an internal module now named window.really_relaxed_json.