alce

What is alce?

The 'alce' npm package is a lightweight JSON parser and stringifier that is designed to be more forgiving with JSON syntax errors. It allows for comments and trailing commas in JSON, which are not supported by the standard JSON.parse and JSON.stringify methods.

What are alce's main functionalities?

Parsing JSON with comments and trailing commas

This feature allows you to parse JSON strings that include comments and trailing commas, which are typically not allowed in standard JSON. The 'alce' package will ignore these and still parse the JSON correctly.

const alce = require('alce');
const jsonString = '{ "key1": "value1", // this is a comment
"key2": "value2", }';
const parsed = alce.parse(jsonString);
console.log(parsed);

Stringifying JSON with options

This feature allows you to convert a JavaScript object into a JSON string with options for formatting, such as indentation. This can be useful for creating human-readable JSON strings.

const alce = require('alce');
const jsonObject = { key1: 'value1', key2: 'value2' };
const jsonString = alce.stringify(jsonObject, null, 2);
console.log(jsonString);

Other packages similar to alce

json5

The 'json5' package is similar to 'alce' in that it allows for more lenient JSON parsing, including support for comments, trailing commas, and more. However, 'json5' also supports additional features like single-quoted strings and unquoted object keys, making it more versatile in some cases.

hjson

The 'hjson' package is another alternative that offers a more human-friendly JSON format. It supports comments, trailing commas, and even multi-line strings. Compared to 'alce', 'hjson' provides a more extensive set of features aimed at improving the readability and writability of JSON.

README

ALCE

Accepting Language Config Environment - "Alice"

Human friendly, machine editable, JSON-like config file format. Takes the JSON out of humans' nightmares.

Extends JSON to allow for:

• Comments
• Regular expressions
• Relaxed identifier and syntax handling

Example

{
  // Section 1. Global config
  content: "foo",

  // Section 2. Environment config
  // WARN: A meaningful here be dragons comment
  otherContent: [
    // Note that trailing spaces and single quotes don't cause mass chaos
    'see!',
  ]
}

Usage

npm install --save alce

var ALCE = require('alce');

var config = ALCE.parse(configSource, {meta: true});
config.set('key', 'new value');
config.toString();
config.toObject();

API

ALCE.parse(configSource, options)

Parses a string containing a ACLE source file. Returns an ACLE object.

• configSource: String representation of the configuration file
• options: Options hash.
  • meta : Set to truthy to return an editable version of the config that may be reconstructed. Falsy returns generic javascript object. See #toObject.
  • Formatter options. See Formatters for more info

ALCE.stringify(object, options)

Converts a ACLE or javascript object to it's string representation.

• object: Object to convert to a string
• options: Formatter options when converting a javascript object. See Formatters for more info.

Metadata Objects

#get(id)

Returns the ACLE or primitive value stored on the object under a given key. undefined if no key exists.

#set(id, value)

Sets value to id converting to an ACLE object as necessary. If replacing an existing value, the formatting of that value will be maintained. If creating a new value, or child values, will use the rules defined in the options formatters.

#remove(id)

Removes the key specified by id.

Array-like methods

ACLE instances representing arrays additionally implement:

• length
• push
• pop
• unshift
• shift
• splice

All of which behave as they would if operating on an normal array.

#toString()

Returns the current config node contents in as close to the user's input format as possible.

#toObject()

Returns a generic javascript object with all config values stripped of any metadata. Useful for passing to other APIs or when metadata is not necessary.

Formatters

Formatters control how newly created nodes are rendering. The may modify the preamble, prologue, and if applicable innerPrologue, fields on the new objects to control the formatting around the new object.

#seedIndent(parent, object)

Called for both parsed and new objects, allowing for the formatter to determine any state information necessary.

  seedIndent: function(parent, object) {
    if (parent) {
      object.indent = exports.calcIndent(parent.preamble || '') + (parent.isArray ? '  ' : '');
    } else {
      object.indent = '';
    }
  },

#objectFormatter(parent, object)

Called when a new object or array is created. Generally parent will be an array instance or a property. The isArray field may be used to determine if parent or object is an array.

  objectFormatter: function(parent, object) {
    object.innerPrologue = '\n' + object.indent;
  },

#insertFormatter(parent, insert)

Called when a new value is inserted into an array or object instance. insert will be pushed to the end of the parent.children list after this operation occurs.

  insertFormatter: function(parent, insert) {
    var indent = parent.indent || ALCE.calcIndent(parent.preamble);
    insert.preamble = (parent.children.length ? ',' : '') + '\n  ' + indent;
  },

#propertyFormatter(parent, property)

Called when a new property is created. This is useful for defining the separator value for a property.

  propertyFormatter: function(parent, property) {
    property.separator = ': ';
  }

ALCE.TWO_SPACE_FORMATTER

Formatter options that output two space indented data structures with trailing commas. May be passed directly into the options parameter for both parse and serialize.

ALCE.calcIndent(preamble)

Utilitity method for formatters. Determines the indentation that should be used for a node relative to a given prefix. This is helpful for the inserFormatter to determine where to align new children inserted into an object.