A JavaScript library for working with the CFG configuration format.
The CFG configuration format is a text format for configuration files which is similar to, and a superset of, the JSON format. It dates from before its first announcement in 2008 and has the following aims:
* Allow a hierarchical configuration scheme with support for key-value mappings and lists.
* Support cross-references between one part of the configuration and another.
* Provide a string interpolation facility to easily build up configuration values from other configuration values.
* Provide the ability to compose configurations (using include and merge facilities).
* Provide the ability to access real application objects safely, where supported by the platform.
* Be completely declarative.
It overcomes a number of drawbacks of JSON when used as a configuration format:
* JSON is more verbose than necessary.
* JSON doesn’t allow comments.
* JSON doesn’t provide first-class support for dates and multi-line strings.
* JSON doesn’t allow trailing commas in lists and mappings.
* JSON doesn’t provide easy cross-referencing, interpolation, or composition.
Installation
============
You can use this package using npm install cfg-lib and then const config = require('cfg-lib') in your code.
Exploration
============
To explore CFG functionality for JavaScript, we can just use the node Read-Eval-Print-Loop (REPL). You can invoke it using
``
$ node
Getting Started with CFG in JavaScript
======================================
A configuration is represented by an instance of the Config class. The constructor for this class can be passed a filename or a stream which contains the text for the configuration. The text is read in, parsed and converted to an object that you can then query. A simple example:
`
a: 'Hello, '
b: 'world!'
c: {
d: 'e'
}
'f.g': 'h'
christmas_morning:
home:
foo:
Loading a configuration
=======================
The configuration above can be loaded as shown below. In the REPL shell:
`
> const config = require('cfg-lib');
undefined
> let cfg = new config.Config("test0.cfg");
undefined
Usage in a browser
==================
In a browser, API elements are exposed in the CFG namespace:
`
let stream = CFG.makeStream('abc: 1');
let cfg = new CFG.Config(stream);
let d = cfg.asDict();
console.log(d);
The above code would print the object { abc: 1 } in the console.
Access elements with keys
=========================
Accessing elements of the configuration with a simple key uses the get method:
`
> cfg.get('a')
'Hello, '
> cfg.get('b')
'world!'
Access elements with paths
==========================
As well as simple keys, elements can also be accessed using path strings:`
> cfg.get('c.d')
'e'
Here, the desired value is obtained in a single step, by (under the hood) walking the path – first getting the mapping at key c, and then the value at d in the resulting mapping.
Note that you can have simple keys which look like paths:
`
> cfg.get('f.g')
'h'
If a key is given that exists in the configuration, it is used as such, and if it is not present in the configuration, an attempt is made to interpret it as a path. Thus, is present and accessed via key, whereas c.d is not an existing key, so is interpreted as a path.
Access to date/time objects
===========================
You can also get native date/time objects from a configuration, by using an ISO date/time pattern in a backtick-string:`
> cfg.get('christmas_morning')
2019-12-25T08:39:49.000Z
Access to environment variables
===============================
To access an environment variable, use a backtick-string of the form $VARNAME:`
> cfg.get('home')
'/home/vinay'
You can specify a default value to be used if an environment variable isn’t present using the form. Whatever string follows the pipe character (including the empty string) is returned if VARNAME is not a variable in the environment.`
> cfg.get('foo')
'bar'
For more information, see the CFG documentation.