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

``javascript
{
// 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
`

`javascript
var ALCE = require('alce');

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

API

$3

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

$3

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.

$3

#### #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.

$3

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.

$3

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

`javascript
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.

`javascript
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.

`javascript
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.

`javascript
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.