states
Version:
Add simple state machine to Javascript objects
40 lines (35 loc) • 14.8 kB
HTML
<html> <head> <title>states.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <div id="jump_to"> Jump To … <div id="jump_wrapper"> <div id="jump_page"> <a class="source" href="camelize.html"> camelize.coffee </a> <a class="source" href="states.html"> states.coffee </a> </div> </div> </div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> states.coffee </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-1">¶</a> </div> <p><strong>states</strong> lets you add a simple state machine to Javascript objects</p> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">¶</a> </div> <h3>Helpers (private)</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">¶</a> </div> <p>import camelize helper</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">camelize = </span><span class="nx">require</span><span class="p">(</span><span class="s">'./camelize'</span><span class="p">)</span></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">¶</a> </div> <p>get the name for the exit callback called for a given state</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">onExitCallbackName = </span><span class="nf">(state)-></span>
<span class="s">"onExit</span><span class="si">#{</span><span class="nx">camelize</span><span class="p">(</span><span class="nx">state</span><span class="p">)</span><span class="si">}</span><span class="s">"</span>
</pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">¶</a> </div> <p>get the name for the enter callback called for a given state </p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">onEnterCallbackName = </span><span class="nf">(state)-></span>
<span class="s">"onEnter</span><span class="si">#{</span><span class="nx">camelize</span><span class="p">(</span><span class="nx">state</span><span class="p">)</span><span class="si">}</span><span class="s">"</span></pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</a> </div> <h3>Exported (public)</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">¶</a> </div> <p>states({obj}, ["a", "list", "of", "states"])</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">states = </span><span class="nf">(instance, states)-></span>
<span class="nv">instance._possibleStates = </span><span class="nx">states</span>
</pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">¶</a> </div> <p>start in the first state</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nv">instance._state = </span><span class="nx">states</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
</pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">¶</a> </div> <p>setup {obj}.is{CamelizedStateName}() helpers that return true if in that state</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">for</span> <span class="nx">state</span> <span class="k">in</span> <span class="nx">states</span>
<span class="nx">do</span> <span class="nf">(state, instance)-></span>
<span class="nx">instance</span><span class="p">[</span><span class="s">"is</span><span class="si">#{</span><span class="nx">camelize</span><span class="p">(</span><span class="nx">state</span><span class="p">)</span><span class="si">}</span><span class="s">"</span><span class="p">]</span> <span class="o">=</span> <span class="nf">()-></span>
<span class="k">this</span><span class="p">.</span><span class="nx">_state</span> <span class="o">is</span> <span class="nx">state</span>
</pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">¶</a> </div> <p>{obj}.states() returns list of possible states</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">instance</span><span class="p">[</span><span class="s">'states'</span><span class="p">]</span> <span class="o">=</span> <span class="nf">()-></span>
<span class="k">this</span><span class="p">.</span><span class="nx">_possibleStates</span>
</pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">¶</a> </div> <p>{obj}.state({state}) sets the state to newState if passed, otherwise returns the current state name</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">instance</span><span class="p">[</span><span class="s">'state'</span><span class="p">]</span> <span class="o">=</span> <span class="nf">(newState = null)-></span>
<span class="k">if</span> <span class="nx">newState</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</a> </div> <p>state has been passed, set it</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">if</span> <span class="nx">newState</span> <span class="k">in</span> <span class="k">this</span><span class="p">.</span><span class="nx">_possibleStates</span>
<span class="nv">oldState = </span><span class="k">this</span><span class="p">.</span><span class="nx">_state</span>
</pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">¶</a> </div> <p>if event handler defined for leaving old state, call it</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nv">exitCallbackName = </span><span class="nx">onExitCallbackName</span><span class="p">(</span><span class="nx">oldState</span><span class="p">)</span>
<span class="k">if</span> <span class="nx">exitCallbackName</span> <span class="k">of</span> <span class="k">this</span>
<span class="k">this</span><span class="p">[</span><span class="nx">exitCallbackName</span><span class="p">]()</span>
</pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">¶</a> </div> <p>if event handler defined for entering new state, call it</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nv">enterCallbackName = </span><span class="nx">onEnterCallbackName</span><span class="p">(</span><span class="nx">newState</span><span class="p">)</span>
<span class="k">if</span> <span class="nx">enterCallbackName</span> <span class="k">of</span> <span class="k">this</span>
<span class="k">this</span><span class="p">[</span><span class="nx">enterCallbackName</span><span class="p">]()</span>
<span class="k">this</span><span class="p">.</span><span class="nv">_state = </span><span class="nx">newState</span>
<span class="k">else</span></pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">¶</a> </div> <p>error thrown on invalid states</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">throw</span><span class="p">(</span><span class="s">"Invalid state: </span><span class="si">#{</span><span class="nx">newState</span><span class="si">}</span><span class="s">"</span><span class="p">)</span>
<span class="k">else</span></pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">¶</a> </div> <p>state wasn't passed, return existing state</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">this</span><span class="p">.</span><span class="nx">_state</span>
</pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">¶</a> </div> <p>{obj}.onExitState({state}, {callback}) attaches event handler that's called when {state} is exited</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">instance</span><span class="p">[</span><span class="s">'onExitState'</span><span class="p">]</span> <span class="o">=</span> <span class="nf">(state, callback)-></span>
<span class="k">if</span> <span class="nx">state</span> <span class="k">in</span> <span class="k">this</span><span class="p">.</span><span class="nx">_possibleStates</span>
<span class="k">this</span><span class="p">[</span><span class="nx">onExitCallbackName</span><span class="p">(</span><span class="nx">state</span><span class="p">)]</span> <span class="o">=</span> <span class="nx">callback</span>
<span class="k">else</span>
<span class="k">throw</span><span class="p">(</span><span class="s">"Invalid state: </span><span class="si">#{</span><span class="nx">state</span><span class="si">}</span><span class="s">"</span><span class="p">)</span>
</pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">¶</a> </div> <p>{obj}.onEnterState({state}, {callback}) attaches event handler that's called when {state} in entered</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">instance</span><span class="p">[</span><span class="s">'onEnterState'</span><span class="p">]</span> <span class="o">=</span> <span class="nf">(state, callback)-></span>
<span class="k">if</span> <span class="nx">state</span> <span class="k">in</span> <span class="k">this</span><span class="p">.</span><span class="nx">_possibleStates</span>
<span class="k">this</span><span class="p">[</span><span class="nx">onEnterCallbackName</span><span class="p">(</span><span class="nx">state</span><span class="p">)]</span> <span class="o">=</span> <span class="nx">callback</span>
<span class="k">else</span>
<span class="k">throw</span><span class="p">(</span><span class="s">"Invalid state: </span><span class="si">#{</span><span class="nx">state</span><span class="si">}</span><span class="s">"</span><span class="p">)</span></pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</a> </div> <p>export top level states function </p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">module.exports = </span><span class="nx">states</span>
</pre></div> </td> </tr> </tbody> </table> </div> </body> </html>