diff --git a/docs/docco.css b/docs/docco.css new file mode 100644 index 0000000..bd54134 --- /dev/null +++ b/docs/docco.css @@ -0,0 +1,194 @@ +/*--------------------- Layout and Typography ----------------------------*/ +body { + font-family: 'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif; + font-size: 15px; + line-height: 22px; + color: #252519; + margin: 0; padding: 0; +} +a { + color: #261a3b; +} + a:visited { + color: #261a3b; + } +p { + margin: 0 0 15px 0; +} +h4, h5, h6 { + color: #333; + margin: 6px 0 6px 0; + font-size: 13px; +} + h2, h3 { + margin-bottom: 0; + color: #000; + } + h1 { + margin-top: 40px; + margin-bottom: 15px; + color: #000; + } +#container { + position: relative; +} +#background { + position: fixed; + top: 0; left: 525px; right: 0; bottom: 0; + background: #f5f5ff; + border-left: 1px solid #e5e5ee; + z-index: -1; +} +#jump_to, #jump_page { + background: white; + -webkit-box-shadow: 0 0 25px #777; -moz-box-shadow: 0 0 25px #777; + -webkit-border-bottom-left-radius: 5px; -moz-border-radius-bottomleft: 5px; + font: 10px Arial; + text-transform: uppercase; + cursor: pointer; + text-align: right; +} +#jump_to, #jump_wrapper { + position: fixed; + right: 0; top: 0; + padding: 5px 10px; +} + #jump_wrapper { + padding: 0; + display: none; + } + #jump_to:hover #jump_wrapper { + display: block; + } + #jump_page { + padding: 5px 0 3px; + margin: 0 0 25px 25px; + } + #jump_page .source { + display: block; + padding: 5px 10px; + text-decoration: none; + border-top: 1px solid #eee; + } + #jump_page .source:hover { + background: #f5f5ff; + } + #jump_page .source:first-child { + } +table td { + border: 0; + outline: 0; +} + td.docs, th.docs { + max-width: 450px; + min-width: 450px; + min-height: 5px; + padding: 10px 25px 1px 50px; + overflow-x: hidden; + vertical-align: top; + text-align: left; + } + .docs pre { + margin: 15px 0 15px; + padding-left: 15px; + } + .docs p tt, .docs p code { + background: #f8f8ff; + border: 1px solid #dedede; + font-size: 12px; + padding: 0 0.2em; + } + .pilwrap { + position: relative; + } + .pilcrow { + font: 12px Arial; + text-decoration: none; + color: #454545; + position: absolute; + top: 3px; left: -20px; + padding: 1px 2px; + opacity: 0; + -webkit-transition: opacity 0.2s linear; + } + td.docs:hover .pilcrow { + opacity: 1; + } + td.code, th.code { + padding: 14px 15px 16px 25px; + width: 100%; + vertical-align: top; + background: #f5f5ff; + border-left: 1px solid #e5e5ee; + } + pre, tt, code { + font-size: 12px; line-height: 18px; + font-family: Menlo, Monaco, Consolas, "Lucida Console", monospace; + margin: 0; padding: 0; + } + + +/*---------------------- Syntax Highlighting -----------------------------*/ +td.linenos { background-color: #f0f0f0; padding-right: 10px; } +span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; } +body .hll { background-color: #ffffcc } +body .c { color: #408080; font-style: italic } /* Comment */ +body .err { border: 1px solid #FF0000 } /* Error */ +body .k { color: #954121 } /* Keyword */ +body .o { color: #666666 } /* Operator */ +body .cm { color: #408080; font-style: italic } /* Comment.Multiline */ +body .cp { color: #BC7A00 } /* Comment.Preproc */ +body .c1 { color: #408080; font-style: italic } /* Comment.Single */ +body .cs { color: #408080; font-style: italic } /* Comment.Special */ +body .gd { color: #A00000 } /* Generic.Deleted */ +body .ge { font-style: italic } /* Generic.Emph */ +body .gr { color: #FF0000 } /* Generic.Error */ +body .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +body .gi { color: #00A000 } /* Generic.Inserted */ +body .go { color: #808080 } /* Generic.Output */ +body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +body .gs { font-weight: bold } /* Generic.Strong */ +body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +body .gt { color: #0040D0 } /* Generic.Traceback */ +body .kc { color: #954121 } /* Keyword.Constant */ +body .kd { color: #954121; font-weight: bold } /* Keyword.Declaration */ +body .kn { color: #954121; font-weight: bold } /* Keyword.Namespace */ +body .kp { color: #954121 } /* Keyword.Pseudo */ +body .kr { color: #954121; font-weight: bold } /* Keyword.Reserved */ +body .kt { color: #B00040 } /* Keyword.Type */ +body .m { color: #666666 } /* Literal.Number */ +body .s { color: #219161 } /* Literal.String */ +body .na { color: #7D9029 } /* Name.Attribute */ +body .nb { color: #954121 } /* Name.Builtin */ +body .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +body .no { color: #880000 } /* Name.Constant */ +body .nd { color: #AA22FF } /* Name.Decorator */ +body .ni { color: #999999; font-weight: bold } /* Name.Entity */ +body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +body .nf { color: #0000FF } /* Name.Function */ +body .nl { color: #A0A000 } /* Name.Label */ +body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +body .nt { color: #954121; font-weight: bold } /* Name.Tag */ +body .nv { color: #19469D } /* Name.Variable */ +body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +body .w { color: #bbbbbb } /* Text.Whitespace */ +body .mf { color: #666666 } /* Literal.Number.Float */ +body .mh { color: #666666 } /* Literal.Number.Hex */ +body .mi { color: #666666 } /* Literal.Number.Integer */ +body .mo { color: #666666 } /* Literal.Number.Oct */ +body .sb { color: #219161 } /* Literal.String.Backtick */ +body .sc { color: #219161 } /* Literal.String.Char */ +body .sd { color: #219161; font-style: italic } /* Literal.String.Doc */ +body .s2 { color: #219161 } /* Literal.String.Double */ +body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +body .sh { color: #219161 } /* Literal.String.Heredoc */ +body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +body .sx { color: #954121 } /* Literal.String.Other */ +body .sr { color: #BB6688 } /* Literal.String.Regex */ +body .s1 { color: #219161 } /* Literal.String.Single */ +body .ss { color: #19469D } /* Literal.String.Symbol */ +body .bp { color: #954121 } /* Name.Builtin.Pseudo */ +body .vc { color: #19469D } /* Name.Variable.Class */ +body .vg { color: #19469D } /* Name.Variable.Global */ +body .vi { color: #19469D } /* Name.Variable.Instance */ +body .il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/docs/nconf.html b/docs/nconf.html new file mode 100644 index 0000000..9b287e9 --- /dev/null +++ b/docs/nconf.html @@ -0,0 +1,103 @@ +
nconf.js | |
---|---|
/*
+ * nconf.js: Top-level include for the nconf module
+ *
+ * (C) 2011, Charlie Robbins
+ *
+ */
+
+require.paths.unshift(__dirname);
+
+var nconf = exports;
+
+nconf.stores = require('nconf/stores'); | |
function use (type, options)+ +@type {string} Type of the nconf store to use.+ +@options {Object} Options for the store instance.+ +Sets the active | nconf.use = function (type, options) {
+ nconf.store = new nconf.stores.create(type, options);
+}; |
function get (key, callback)+ +@key {string} Key to retrieve for this instance.+ +@callback {function} Optional Continuation to respond to when complete.+ +Retrieves the value for the specified key (if any). | nconf.get = function (key, callback) {
+ return nconf.store.get(key, callback);
+}; |
function set (key, value, callback)+ +@key {string} Key to set in this instance+ +@value {literal|Object} Value for the specified key+ +@callback {function} Optional Continuation to respond to when complete.+ +Sets the | nconf.set = function (key, value, callback) {
+ return nconf.store.set(key, value, callback);
+}; |
function clear (key, callback)+ +@key {string} Key to remove from this instance+ +@callback {function} Optional Continuation to respond to when complete.+ +Removes the value for the specified | nconf.clear = function (key, callback) {
+ return nconf.store.clear(key, callback);
+}; |
function load (callback)+ +@callback {function} Continuation to respond to when complete.+ +Responds with an Object representing all keys associated in this instance. | nconf.load = function (callback) {
+ if (!nconf.store.load) {
+ var error = new Error('nconf store ' + nconf.store.type + ' has no load() method');
+ if (callback) {
+ return callback (error);
+ }
+
+ throw error;
+ }
+
+ return nconf.store.load(callback);
+}; |
function save (value, callback)+ +@value {Object} Optional Config object to set for this instance+ +@callback {function} Continuation to respond to when complete.+ +Removes any existing configuration settings that may exist in this
+instance and then adds all key-value pairs in | nconf.save = function (value, callback) {
+ if (!callback) {
+ callback = value;
+ value = null;
+ }
+
+ if (!nconf.store.save) {
+ var error = new Error('nconf store ' + nconf.store.type + ' has no save() method');
+ if (callback) {
+ return callback (error);
+ }
+
+ throw error;
+ }
+
+ return nconf.store.save(value, callback);
+}; |
function reset (callback)+ +@callback {function} Optional Continuation to respond to when complete.+ +Clears all keys associated with this instance. | nconf.reset = function (callback) {
+ return nconf.store.reset(callback);
+}; |
function key (arguments)+ +Returns a | nconf.key = function () {
+ return Array.prototype.slice.call(arguments).join(':');
+}; |
function path (key)+ +@key {string} The ':' delimited key to split+ +Returns a fully-qualified path to a nested nconf key. | nconf.path = function (key) {
+ return key.split(':');
+};
+
+ |
stores.js | |
---|---|
/*
+ * stores.js: Top-level include for all nconf stores
+ *
+ * (C) 2011, Charlie Robbins
+ *
+ */
+
+var stores = exports;
+
+function capitalize (str) {
+ return str && str[0].toUpperCase() + str.slice(1);
+};
+
+stores.Memory = require('nconf/stores/memory').Memory;
+stores.File = require('nconf/stores/file').File;
+stores.Redis = require('nconf/stores/redis').Redis; | |
function create (type, options)+ +@type {string} Type of the nconf store to use.+ +@options {Object} Options for the store instance.+ +Creates a store of the specified | stores.create = function (type, options) {
+ return new stores[capitalize(type.toLowerCase())](options);
+};
+
+ |
file.js | |
---|---|
/*
+ * file.js: Simple file storage engine for nconf files
+ *
+ * (C) 2011, Charlie Robbins
+ *
+ */
+
+var fs = require('fs'),
+ util = require('util'),
+ Memory = require('./memory').Memory;
+ | |
function File (options)+ +@options {Object} Options for this instance+ +Constructor function for the File nconf store, a simple abstraction +around the Memory store that can persist configuration to disk. | var File = exports.File = function (options) {
+ if (!options.file) {
+ throw new Error ('Missing required option `files`');
+ }
+
+ Memory.call(this, options);
+
+ this.file = options.file;
+ this.format = options.format || JSON;
+}; |
Inherit from the Memory store | util.inherits(File, Memory); |
function save (value, callback)+ +@value {Object} Ignored Left here for consistency+ +@callback {function} Continuation to respond to when complete.+ +Saves the current configuration object to disk at | File.prototype.save = function (value, callback) {
+ if (!callback) {
+ callback = value;
+ value = null;
+ }
+
+ fs.writeFile(this.file, this.format.stringify(this.store), function (err) {
+ return err ? callback(err) : callback();
+ });
+}; |
function load (callback)+ +@callback {function} Continuation to respond to when complete.+ +Responds with an Object representing all keys associated in this instance. | File.prototype.load = function (callback) {
+ var self = this;
+ fs.readFile(this.file, function (err, data) {
+ if (err) {
+ return callback(err);
+ }
+
+ data = self.format.parse(data.toString());
+ self.store = data;
+ callback(null, self.store);
+ });
+};
+
+ |
memory.js | |
---|---|
/*
+ * memory.js: Simple memory storage engine for nconf configuration(s)
+ *
+ * (C) 2011, Charlie Robbins
+ *
+ */
+
+var nconf = require('nconf'); | |
function Memory (options)+ +@options {Object} Options for this instance+ +Constructor function for the Memory nconf store which maintains
+a nested json structure based on key delimiters e.g. | var Memory = exports.Memory = function (options) {
+ options = options || {};
+ this.store = {};
+ this.mtimes = {};
+}; |
function get (key)+ +@key {string} Key to retrieve for this instance.+ +Retrieves the value for the specified key (if any). | Memory.prototype.get = function (key) {
+ var target = this.store,
+ path = nconf.path(key); |
Scope into the object to get the appropriate nested context | while (path.length > 0) {
+ key = path.shift();
+ if (!target[key]) {
+ return;
+ }
+
+ target = target[key];
+ if (path.length === 0) {
+ return target;
+ }
+ }
+}; |
function set (key, value)+ +@key {string} Key to set in this instance+ +@value {literal|Object} Value for the specified key+ +Sets the | Memory.prototype.set = function (key, value) {
+ var target = this.store,
+ path = nconf.path(key);
+ |
Update the | this.mtimes[key] = Date.now();
+ |
Scope into the object to get the appropriate nested context | while (path.length > 1) {
+ key = path.shift();
+ if (!target[key]) {
+ target[key] = {};
+ }
+
+ target = target[key];
+ } |
Set the specified value in the nested JSON structure | key = path.shift();
+ target[key] = value;
+ return true;
+}; |
function clear (key)+ +@key {string} Key to remove from this instance+ +Removes the value for the specified | Memory.prototype.clear = function (key) {
+ var target = this.store,
+ path = nconf.path(key);
+ |
Remove the key from the set of | delete this.mtimes[key];
+ |
Scope into the object to get the appropriate nested context | while (path.length > 1) {
+ key = path.shift();
+ if (!target[key]) {
+ return;
+ }
+
+ target = target[key];
+ }
+ |
Delete the key from the nested JSON structure | key = path.shift();
+ delete target[key];
+ return true;
+}; |
function reset (callback)+ +Clears all keys associated with this instance. | Memory.prototype.reset = function () {
+ this.mtimes = {};
+ this.store = {};
+ return true;
+}
+
+ |
redis.js | |
---|---|
/*
+ * redis.js: Redis storage engine for nconf configuration(s)
+ *
+ * (C) 2011, Charlie Robbins
+ *
+ */
+
+var async = require('async'),
+ eyes = require('eyes'),
+ redis = require('redis'),
+ nconf = require('nconf'),
+ Memory = require('./Memory').Memory; | |
function Redis (options)+ +@options {Object} Options for this instance+ +Constructor function for the Redis nconf store which maintains
+a nested Redis key structure based on key delimiters e.g. + my:nested:key, 'value' + namespace:keys ==> ['my'] + namespace:nested:keys ==> ['key'] + namespace:nested:key ==> 'value' | var Redis = exports.Redis = function (options) {
+ options = options || {}
+ this.namespace = options.namespace || 'nconf';
+ this.host = options.host || 'localhost';
+ this.port = options.port || 6379;
+ this.ttl = options.ttl || 60 * 60 * 1000;
+ this.cache = new Memory();
+ this.redis = redis.createClient(options.port, options.host);
+}; |
function get (key, callback)+ +@key {string} Key to retrieve for this instance.+ +@callback {function} Continuation to respond to when complete.+ +Retrieves the value for the specified key (if any). | Redis.prototype.get = function (key, callback) {
+ var self = this,
+ result = {},
+ now = Date.now(),
+ mtime = this.cache.mtimes[key],
+ fullKey = nconf.key(this.namespace, key);
+ |
If the key exists in the cache and the ttl is less than +the value set for this instance, return from the cache. | if (mtime && now - mtime < this.ttl) {
+ return callback(null, this.cache.get(key));
+ }
+ |
Get the set of all children keys for the | this.redis.smembers(nconf.key(fullKey, 'keys'), function (err, keys) {
+ function addValue (source, next) {
+ self.get(nconf.key(key, source), function (err, value) {
+ if (err) {
+ return next(err);
+ }
+
+ result[source] = value;
+ next();
+ });
+ }
+
+ if (keys && keys.length > 0) { |
If the value to be retrieved is an Object, recursively attempt
+to get the value from redis. Here we use a recursive call to | async.forEach(keys, addValue, function (err) {
+ if (err) {
+ return callback(err);
+ }
+
+ self.cache.set(key, result);
+ callback(null, result);
+ })
+ }
+ else { |
If there are no keys, then the value to be retrieved is a literal +and we can simply return the value from redis directly. | self.redis.get(fullKey, function (err, value) {
+ if (err) {
+ return callback(err);
+ }
+
+ result = JSON.parse(value);
+ if (result) {
+ self.cache.set(key, result);
+ }
+
+ callback(null, result);
+ });
+ }
+ });
+}; |
function set (key, value, callback)+ +@key {string} Key to set in this instance+ +@value {literal|Object} Value for the specified key+ +@callback {function} Continuation to respond to when complete.+ +Sets the | Redis.prototype.set = function (key, value, callback) {
+ var self = this,
+ path = nconf.path(key);
+
+ function addKey (partial, next) {
+ var index = path.indexOf(partial),
+ base = [self.namespace].concat(path.slice(0, index)),
+ parent = nconf.key.apply(null, base.concat(['keys']));
+
+ self.redis.sadd(parent, partial, next);
+ }; |
Iterate over the entire key path and add each key to the +parent key-set if it doesn't exist already. | async.forEach(path, addKey, function (err) {
+ if (err) {
+ return callback(err);
+ }
+
+ var fullKey = nconf.key(self.namespace, key);
+
+ if (!Array.isArray(value) && typeof value === 'object') { |
If the value is an | self._setObject(fullKey, value, callback);
+ }
+ else { |
If the value is a simple literal (or an | value = JSON.stringify(value);
+ self.cache.set(key, value);
+ self.redis.set(fullKey, value, callback);
+ }
+ });
+}; |
function clear (key, callback)+ +@key {string} Key to remove from this instance+ +@callback {function} Continuation to respond to when complete.+ +Removes the value for the specified | Redis.prototype.clear = function (key, callback) {
+ var self = this,
+ result = {},
+ path = [this.namespace].concat(nconf.path(key)),
+ last = path.pop(),
+ fullKey = nconf.key(this.namespace, key); |
Clear the key from the cache for this instance | this.cache.clear(key);
+ |
Remove the | this.redis.srem(nconf.key.apply(null, path.concat(['keys'])), last, function (err) { |
Remove the value from redis by iterating over the set of keys (if any) +and deleting each value. If no keys, then just delete the simple literal. | self.redis.smembers(nconf.key(fullKey, 'keys'), function (err, keys) {
+ function removeValue (child, next) { |
Recursively call | self.clear(nconf.key(key, child), next);
+ }
+
+ if (keys && keys.length > 0) { |
If there are child keys then iterate over them, +removing each child along the way. | async.forEach(keys, removeValue, callback);
+ }
+ else { |
Otherwise if this is just a simple literal, then +simply remove it from Redis directly. | self.redis.del(fullKey, callback);
+ }
+ });
+ });
+}; |
function save (value, callback)+ +@value {Object} Config object to set for this instance+ +@callback {function} Continuation to respond to when complete.+ +Removes any existing configuration settings that may exist in this
+instance and then adds all key-value pairs in | Redis.prototype.save = function (value, callback) {
+ if (Array.isArray(value) || typeof value !== 'object') {
+ return callback(new Error('`value` to be saved must be an object.'));
+ }
+
+ var self = this,
+ keys = Object.keys(value);
+ |
Clear all existing keys associated with this instance. | this.reset(function (err) {
+ if (err) {
+ return callback(err);
+ }
+ |
Iterate over the keys in the new value, setting each of them. | async.forEach(keys, function (key, next) {
+ self.set(key, value[key], next);
+ }, callback);
+ });
+}; |
function load (callback)+ +@callback {function} Continuation to respond to when complete.+ +Responds with an Object representing all keys associated in this instance. | Redis.prototype.load = function (callback) {
+ var self = this,
+ result = {};
+
+ this.redis.smembers(nconf.key(this.namespace, 'keys'), function (err, keys) {
+ if (err) {
+ return callback(err);
+ }
+
+ function addValue (key, next) {
+ self.get(key, function (err, value) {
+ if (err) {
+ return next(err);
+ }
+
+ result[key] = value;
+ next();
+ });
+ }
+
+ async.forEach(keys, addValue, function (err) {
+ return err ? callback(err) : callback(null, result);
+ });
+ });
+}; |
function reset (callback)+ +@callback {function} Continuation to respond to when complete.+ +Clears all keys associated with this instance. | Redis.prototype.reset = function (callback) {
+ var self = this;
+ |
Get the list of of top-level keys, then clear each of them | this.redis.smembers(nconf.key(this.namespace, 'keys'), function (err, existing) {
+ if (err) {
+ return callback(err);
+ }
+
+ async.forEach(existing, function (key, next) {
+ self.clear(key, next);
+ }, callback);
+ });
+}; |
@private function _setObject (key, value, callback)+ +@key {string} Key to set in this instance+ +@value {Object} Value for the specified key+ +@callback {function} Continuation to respond to when complete.+ +Internal helper function for setting all keys of a nested object. | Redis.prototype._setObject = function (key, value, callback) {
+ var self = this,
+ keys = Object.keys(value);
+
+ function addValue (child, next) { |
Add the child key to the parent key-set, then set the value.
+Recursively call | self.redis.sadd(nconf.key(key, 'keys'), child, function (err) {
+ if (err) {
+ return next(err);
+ }
+
+ var fullKey = nconf.key(key, child),
+ childValue = value[child];
+
+ if (!Array.isArray(childValue) && typeof childValue === 'object') {
+ self._setObject(fullKey, childValue, next);
+ }
+ else {
+ childValue = JSON.stringify(childValue);
+ self.redis.set(fullKey, childValue, next);
+ }
+ });
+ }
+ |
Iterate over the keys of the Object and set the appropriate values. | async.forEach(keys, addValue, function (err) {
+ return err ? callback(err) : callback();
+ });
+};
+
+ |