<h4>@options {Object} Options for this instance.</h4>
<p>Constructor function for the Provider object responsible
for exposing the pluggable storage features of <code>nconf</code>.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="kd">var</span><spanclass="nx">Provider</span><spanclass="o">=</span><spanclass="nx">exports</span><spanclass="p">.</span><spanclass="nx">Provider</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">options</span><spanclass="p">)</span><spanclass="p">{</span>
</pre></div></td></tr><trid="section-3"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-3">¶</a></div><p>Setup default options for working with <code>stores</code>,
<code>overrides</code>, <code>process.env</code> and <code>process.argv</code>.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">options</span><spanclass="o">=</span><spanclass="nx">options</span><spanclass="o">||</span><spanclass="p">{};</span>
</pre></div></td></tr><trid="section-4"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-4">¶</a></div><p>Add the default <code>system</code> store for working with
<code>overrides</code>, <code>process.env</code>, <code>process.argv</code> and
a simple in-memory objects.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="k">this</span><spanclass="p">.</span><spanclass="nx">add</span><spanclass="p">(</span><spanclass="s1">'system'</span><spanclass="p">,</span><spanclass="nx">options</span><spanclass="p">);</span>
<spanclass="p">};</span></pre></div></td></tr><trid="section-5"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-5">¶</a></div><h3>function use (name, options)</h3>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'Cannot use reserved name: '</span><spanclass="o">+</span><spanclass="nx">name</span><spanclass="p">);</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'Cannot use reserved name: '</span><spanclass="o">+</span><spanclass="nx">name</span><spanclass="p">);</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'Cannot add store with unknown type: '</span><spanclass="o">+</span><spanclass="nx">type</span><spanclass="p">);</span>
<h4>@name {string} Name of the store to remove from this instance</h4>
<p>Removes a store with the specified <code>name</code> from this instance. Users
are allowed to pass in a type argument (e.g. <code>memory</code>) as name if
this was used in the call to <code>.add()</code>.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">remove</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">name</span><spanclass="p">)</span><spanclass="p">{</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'Cannot use reserved name: '</span><spanclass="o">+</span><spanclass="nx">name</span><spanclass="p">);</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'Cannot remove store that does not exist: '</span><spanclass="o">+</span><spanclass="nx">name</span><spanclass="p">);</span>
<spanclass="p">};</span></pre></div></td></tr><trid="section-9"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-9">¶</a></div><h3>function get (key, callback)</h3>
<p>Retrieves the value for the specified key (if any).</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">get</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">key</span><spanclass="p">,</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span></pre></div></td></tr><trid="section-10"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-10">¶</a></div><p>If there is no callback we can short-circuit into the default
logic for traversing stores.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="k">if</span><spanclass="p">(</span><spanclass="o">!</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
</pre></div></td></tr><trid="section-11"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-11">¶</a></div><p>Otherwise the asynchronous, hierarchical <code>get</code> is
slightly more complicated because we do not need to traverse
the entire set of stores, but up until there is a defined value.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="kd">var</span><spanclass="nx">current</span><spanclass="o">=</span><spanclass="mi">0</span><spanclass="p">,</span>
<spanclass="p">};</span></pre></div></td></tr><trid="section-12"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-12">¶</a></div><h3>function set (key, value, callback)</h3>
<h4>@key {string} Key to set in this instance</h4>
<h4>@value {literal|Object} Value for the specified key</h4>
<h4>@callback {function} <strong>Optional</strong> Continuation to respond to when complete.</h4>
<p>Sets the <code>value</code> for the specified <code>key</code> in this instance.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">set</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">key</span><spanclass="p">,</span><spanclass="nx">value</span><spanclass="p">,</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
<h4>@callback {function} <strong>Optional</strong> Continuation to respond to when complete.</h4>
<p>Clears all keys associated with this instance.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">reset</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
<h4>@key {string} Key to remove from this instance</h4>
<h4>@callback {function} <strong>Optional</strong> Continuation to respond to when complete.</h4>
<p>Removes the value for the specified <code>key</code> from this instance.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">clear</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">key</span><spanclass="p">,</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
<spanclass="k">return</span><spanclass="nx">onError</span><spanclass="p">(</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'Cannot merge non-Object into top-level.'</span><spanclass="p">),</span><spanclass="nx">callback</span><spanclass="p">);</span>
<p>Responds with an Object representing all keys associated in this instance.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">load</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'nconf store '</span><spanclass="o">+</span><spanclass="nx">store</span><spanclass="p">.</span><spanclass="nx">type</span><spanclass="o">+</span><spanclass="s1">' has no loadSync() method'</span><spanclass="p">);</span>
<spanclass="k">return</span><spanclass="nx">next</span><spanclass="p">(</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'nconf store '</span><spanclass="o">+</span><spanclass="nx">store</span><spanclass="p">.</span><spanclass="nx">type</span><spanclass="o">+</span><spanclass="s1">' has no load() method'</span><spanclass="p">));</span>
</pre></div></td></tr><trid="section-17"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-17">¶</a></div><p>If we don't have a callback and the current
then do so.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="k">if</span><spanclass="p">(</span><spanclass="o">!</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
<spanclass="p">};</span></pre></div></td></tr><trid="section-18"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-18">¶</a></div><h3>function save (value, callback)</h3>
<h4>@value {Object} <strong>Optional</strong> Config object to set for this instance</h4>
<h4>@callback {function} Continuation to respond to when complete.</h4>
<p>Removes any existing configuration settings that may exist in this
instance and then adds all key-value pairs in <code>value</code>. </p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">save</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">value</span><spanclass="p">,</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
<spanclass="k">throw</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'nconf store '</span><spanclass="o">+</span><spanclass="nx">store</span><spanclass="p">.</span><spanclass="nx">type</span><spanclass="o">+</span><spanclass="s1">' has no saveSync() method'</span><spanclass="p">);</span>
<spanclass="k">return</span><spanclass="nx">next</span><spanclass="p">(</span><spanclass="k">new</span><spanclass="nb">Error</span><spanclass="p">(</span><spanclass="s1">'nconf store '</span><spanclass="o">+</span><spanclass="nx">store</span><spanclass="p">.</span><spanclass="nx">type</span><spanclass="o">+</span><spanclass="s1">' has no save() method'</span><spanclass="p">));</span>
</pre></div></td></tr><trid="section-19"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-19">¶</a></div><p>If we don't have a callback and the current
store is capable of saving synchronously
then do so.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="k">if</span><spanclass="p">(</span><spanclass="o">!</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
to a synchronous store function is still invoked.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">_execute</span><spanclass="o">=</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">action</span><spanclass="p">,</span><spanclass="nx">syncLength</span><spanclass="cm">/* [arguments] */</span><spanclass="p">)</span><spanclass="p">{</span>
<p>Gets or sets a property representing overrides which supercede all
other values for this instance.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">__defineSetter__</span><spanclass="p">(</span><spanclass="s1">'overrides'</span><spanclass="p">,</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">val</span><spanclass="p">)</span><spanclass="p">{</span><spanclass="nx">updateSystem</span><spanclass="p">.</span><spanclass="nx">call</span><spanclass="p">(</span><spanclass="k">this</span><spanclass="p">,</span><spanclass="s1">'overrides'</span><spanclass="p">,</span><spanclass="nx">val</span><spanclass="p">)</span><spanclass="p">});</span>
<p>Gets or sets a property indicating if we should wrap calls to <code>.get</code>
by checking <code>optimist.argv</code>. Can be a boolean or the pass-thru
options for <code>optimist</code>.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">__defineSetter__</span><spanclass="p">(</span><spanclass="s1">'argv'</span><spanclass="p">,</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">val</span><spanclass="p">)</span><spanclass="p">{</span><spanclass="nx">updateSystem</span><spanclass="p">.</span><spanclass="nx">call</span><spanclass="p">(</span><spanclass="k">this</span><spanclass="p">,</span><spanclass="s1">'argv'</span><spanclass="p">,</span><spanclass="nx">val</span><spanclass="p">)</span><spanclass="p">});</span>
<p>Gets or sets a property indicating if we should wrap calls to <code>.get</code>
by checking <code>process.env</code>. Can be a boolean or an Array of
environment variables to extract.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">__defineSetter__</span><spanclass="p">(</span><spanclass="s1">'env'</span><spanclass="p">,</span><spanclass="kd">function</span><spanclass="p">(</span><spanclass="nx">val</span><spanclass="p">)</span><spanclass="p">{</span><spanclass="nx">updateSystem</span><spanclass="p">.</span><spanclass="nx">call</span><spanclass="p">(</span><spanclass="k">this</span><spanclass="p">,</span><spanclass="s1">'env'</span><spanclass="p">,</span><spanclass="nx">val</span><spanclass="p">)</span><spanclass="p">});</span>
<spanclass="nx">Provider</span><spanclass="p">.</span><spanclass="nx">prototype</span><spanclass="p">.</span><spanclass="nx">__defineGetter__</span><spanclass="p">(</span><spanclass="s1">'env'</span><spanclass="p">,</span><spanclass="kd">function</span><spanclass="p">()</span><spanclass="p">{</span><spanclass="k">return</span><spanclass="k">this</span><spanclass="p">.</span><spanclass="nx">_env</span><spanclass="p">});</span></pre></div></td></tr><trid="section-24"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-24">¶</a></div><p>Throw the <code>err</code> if a callback is not supplied</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="kd">function</span><spanclass="nx">onError</span><spanclass="p">(</span><spanclass="nx">err</span><spanclass="p">,</span><spanclass="nx">callback</span><spanclass="p">)</span><spanclass="p">{</span>
<spanclass="p">}</span></pre></div></td></tr><trid="section-25"><tdclass="docs"><divclass="pilwrap"><aclass="pilcrow"href="#section-25">¶</a></div><p>Helper function for working with the
default <code>system</code> store for providers.</p></td><tdclass="code"><divclass="highlight"><pre><spanclass="kd">function</span><spanclass="nx">updateSystem</span><spanclass="p">(</span><spanclass="nx">prop</span><spanclass="p">,</span><spanclass="nx">value</span><spanclass="p">)</span><spanclass="p">{</span>
