conar

Conar

conar (pronounced like the name connor) provides a quick, customizable way to combine environment, argument, and configuration file values at runtime into a configuration object.

api

conar supports a few different things:

• (opts:object):
  creates an instance of conar with options. these options are currently only useful for test hooks; it supports:

{
  env:{},  // an environment object to mock out process.env
  arg: [] // an argument object to mock out process.argv
}

• .env:number:
  see order() method below; provides support for ordering the parsing engine different; represents the env parser

• .arg:number:
  see order() method below; provides support for ordering the parsing engine different; represents the arg parser

• .config:number:
  see order() method below; provides support for ordering the parsing engine different; represents the config parser bengreenier/lconf

once you've created an instance, that instance has the following api methods:

• parse(file:string, [regex:RegExp]):
  parse a file using bengreenier/lconf for configuration. supports json, yaml, yml, and js (with module.exports = {};) if file is a directory, all files inside the directory will be included. if regex is given, file (if actual file) or all files in directory (if file is a directory) will be compared against regex, and added if regex.test(filePath) returns true.

• order(first:number, second:number, third:number):
  set the order for parsing; takes one of the .<source> parameters from off conar. parsing happens in the order first<-second<-third where <- indicates overwrite

• defaults(default:object):
  adds default values for certain properties; when parsed, these will be overriden by any active parsers

• config(key:string):
  blacklists a key from being parsed by this source

• config(bool:boolean):
  prevents this sources parser from being run at all (disables it)

• arg(key:string):
  blacklists a key from being parsed by this source

• arg(bool:boolean):
  prevents this sources parser from being run at all (disables it)

• env(key:string):
  blacklists a key from being parsed by this source

• env(bool:boolean):
  prevents this sources parser from being run at all (disables it)

• suppress([bool:boolean]):
  when set, any exceptions that would normally be thrown by parsers will not be thrown. bool is optional, defaults to true

• opts():
  this call does the actual processing, and returns an object.

• log(func:function):
  test hook for writing some internal logging info; should be given a function which will be called with one argument. (hint: console.log)

all methods can be chained, unless specifically indicated otherwise (like opts()).

examples

var conar = require('conar');
var config = conar().opts(); // returns all arguments parsed via command line

var conar = require('conar');
var config = conar().defaults({port:3000}).opts(); // sets a default value port to 3000

var conar = require('conar');
var config = conar()
              .env("port") // whitelist port environment variable
              .parse("config.json") // parse some config file
              .defaults({port: 1337}) // set a default port
              .opts(); // do the work, get an object

var conar = require('conar');
var config = conar()
              .env("port") // whitelist port environment variable
              .env("prod") // whitelist prod environment variable
              .arg("prod") // blacklist prod argument (can't be set like --prod)
              .config(false) // disable config parsing altogether
              .defaults({port: 1337}) // set a default port value to 1337
              .opts(); // do the work, get an object

hopefully you get the idea.