README

User Config

Loads an application's user configuration.

Installation

$ npm install find-user-app-config

Usage

var find = require( 'find-user-app-config' );

find( [options] )

Loads an application's user configuration.

var config = find();

The function accepts the following options:

dir: user configuration directory. The default value is determined according to the host OS.
basename: basename of a file within the user configuration directory which contains user application settings. The default value is the application name.
fmt: user configuration file format. The default value is either determined from a basename filename extension or ini.

User configuration directory locations vary from platform to platform. By default, this module only supports standard directory locations. To accommodate non-standard user configuration directories, e.g., $HOME/.config/<app_name> on Mac OS X, the module supports a dir option.

var homedir = require( 'utils-homedir' ),
    path = require( 'path' );

var dir = path.join( homedir(), '.config', 'my-app-name' );

var config = find({
    'dir': dir
});

By default, this module assumes that a configuration file name matches the application name. To specify a different configuration file basename, set the basename option.

var config = find({
    'basename': '.config'
});

If a basename does not include a file extension, this module attempts to either find a file having a supported extension or parse a file as INI. If a basename includes an extension, the module always parses the configuration according to the extension.

// Always parsed as YAML...
var config = find({
    'basename': '.config.yaml'
});

Alternatively, to parse a configuration file not having an extension according to a specified format, set the fmt option.

// Parse as YAML...
var config = find({
    'basename': '.configrc',
    'fmt': 'yaml'
});

===

find.parser( extname[, parser] )

Returns a parser for the specified extension.

var parser = find.parser( '.json' );

Including the . when specifying an extension is optional.

var parser = find.parser( 'json' );

To support additional file formats or to override a parser, provide a parser function for an associated extension.

var parser = require( 'my-special-fmt-parser' );

find.parser( '<my-ext>', parser );

Once a parser is set, find invocations will load and parse provided files accordingly. For more details, see app-etc-load.

Notes

If a file extension is omitted when specifying a file basename, this module will search for the first file having the basename and a supported extension. For supported extensions, see app-etc-load.
If a file basename does not begin with a ., this module will search for both hidden and non-hidden files. This also applies for inferred basenames; e.g., <pkg_name>. If <pkg_name> is super-app, this module will search for and load either a .super-app.<ext> or a super-app.<ext> file.
Depending on provided options and the existence of a user configuration directory, various strategies are used to resolve user application configuration files; e.g., see source. The basic strategy is as follows:
- Search for a configuration dot or rc file in a user configuration directory.
- Search for a either a hidden or non-hidden configuration file having a supported extension in a user configuration directory.
- Search for a configuration dot or rc file by walking up from the current working directory.
If you encounter unexpected results, set the DEBUG environment variable to see the steps taken to resolve a configuration file.
```
$ DEBUG=find-user-app-config:* node <path/to/your/app>
```

Examples

var path = require( 'path' ),
    cwd = require( 'utils-cwd' ),
    find = require( 'find-user-app-config' );

// Find a user application config...
var config = find({
    'dir': path.join( cwd(), 'examples', 'foo' ),
    'basename': 'beep',
    'fmt': 'toml'
});
console.dir( config );
/*
    {
        'server': {
            'port': 8080,
            'address': '127.0.0.1',
            'ssl': true,
            'key': '',
            'cert': ''
        },
        'logger': {
            'level': 'debug'
        }
    }
*/

To run the example code from the top-level application directory,

$ DEBUG=* node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

find-user-app-config

Usage no npm install needed!