prefsink¶
- Version:
- 0.2.0 (2012-05-07)
- Module:
require("prefsink");
Manage user-provided preferences for your Node programs through a file in the user’s home directory, environment variables and default values.
var prefsink = require("prefsink");
// Assume ~/.buster contains
// module.exports = {
// reporter: "specification"
// };
prefsink.load("buster", function (err, prefs) {
if (err) { throw err; }
prefs.get("reporter", "dots"); //=> "specification"
prefs.get("logLevel", "warn"); //=> "warn"
process.env.BUSTER_LOG_LEVEL = "info"
prefs.get("logLevel", "warn"); //=> "info"
});
Preference modules¶
prefsink.load("myproject", function (err, prefs) {
/* ... */
});
Prefsink will use the first available of the following files (~/
denotes
‘home directory’, which on Windows means the directory specified by
USERPROFILE
):
~/.myproject.d/index.js
(lets the user organize all related files in one directory)~/.myproject.js
(the suffix may be useful for editor syntax highlighting etc)~/.myproject
(iconic Unix style preference file)
Prefsink expects the settings file to be a node module that can be
require
‘d.
If you want Prefsink to look for other files, or with a different ordering,
just set prefsink.locations
to an array of desired paths. The array should
contain full paths, optionally with "{namespace}"
which will be replaced
with the namespace.
Preference property lookup¶
prefs.get("id", 42);
Given one of those modules, Prefsink uses the following property lookup:
- Does the preference module export
id
? Use that - Is
process.env.MYPROJECT_ID
set? Use that - Otherwise, use the default (
42
in the above example)
Properties¶
-
prefsink.
home
¶ String, contains the path to where Prefsink thinks the user’s home directory is.
-
prefsink.
locations
¶ Array of strings. The locations Prefsink will attempt to load, in preferred order. Default value is:
exports.locations = [ Path.join(exports.home, ".{namespace}.d", "index.js"), Path.join(exports.home, ".{namespace}.js"), Path.join(exports.home, ".{namespace}") ];
Methods¶
-
prefsink.
findFile
()¶ prefsink.findFile(namespace, callback(err, fileName));
Finds the filename for the preferred preference module according to the lookup described above. Yields
null
if none of the files are available. The error object is currently not being used as any error will simply result in anull
file name.
-
prefsink.
findFileSync
()¶ prefsink.findFileSync(namespace);
Blocking version of
findFile
.
-
prefsink.
create
()¶ var prefsJar = prefsink.create(namespace[, prefs[, source]]);
Creates a preference “jar” (see API below).
namespace
:- A string, typically the name of your project, like “buster”. It will be used to find environment variables relevant to your preferences.
prefs
:- An object with properties. When asking the preference jar for properties, properties on this object will be preferred.
source
:- A string that reveals which source
prefs
were loaded from. It’s simply exposed asprefsJar.source
.
-
prefsink.
load
()¶ prefsink.load(namespace, callback(err, prefsJar));
Figures out which file to use, loads its contents and creates a preference jar that is passed to the callback. The error object is used when
require
-ing the preference file fails (i.e. when the file exists but is not loadable).
-
prefsink.
loadSync
()¶ prefsink.loadSync(namespace);
Blocking version of
load
.
Preference jar¶
-
prefJar.
namespace
¶ The corresponding string passed in as argument to
create
-
prefJar.
source
¶ The corresponding string passed in as argument to
create
-
prefJar.
get
()¶ prefJar.get(name[, defaultVal]);
Returns the named property according to the property lookup described above. Dashes and spaces are converted to underscores when trying environment variables, e.g.
get("something-nice")
will try the environment variableMYPROJECT_SOMETHING_NICE
. Camel cased properties will map to underscored and upper cased environment variables.