Consequence

/*

• Consequence.js v 0.2.0

• LICENSE
• The MIT License
• Copyright (c) 2011 Sean E. Dunn
• Permission is hereby granted, free of charge, to any person obtaining a copy
• of this software and associated documentation files (the "Software"), to deal
• in the Software without restriction, including without limitation the rights
• to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
• copies of the Software, and to permit persons to whom the Software is
• furnished to do so, subject to the following conditions:
• The above copyright notice and this permission notice shall be included in
• all copies or substantial portions of the Software.
• THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
• IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
• FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
• AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
• LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
• OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
• THE SOFTWARE.

• OVERVIEW
• Consequence.js is a Javascript library for reactive programming:
• http://en.wikipedia.org/wiki/Reactive_programming
• With Consequence.js, one can set a state clause that, when satisfied at any
• time, results in the execution of bound imperative handlers, for either the
• positive (true) case, or the negative (false) case.
• This library can be used when a programmer would rather say "whenever some
• complex state set X happens, do Y, and let me not worry about when", instead
• of "whenever I can, check whether some complex state set X is happening and
• do Y". Example domains where this could be useful are games, user
• interfaces, and, to give an example where this exists presently, in
• spreadsheets.

• IN DETAIL
• In the traditional imperitive model, it is the responsibility of the
• programmer to write constructs that regularly check whether state has been
• satisfied in order to execute subsequent instructions. In the Consequence.js
• reactive programming model, a binding is made between the state clause which
• must be satisfied at some point in the future, and the code which handles
• the positive and negative results of that state.
• Consequence.js provides a simple binding for describing what variables are
• being watched, what test determines the trigger condition, and what to
• execute if the test is true or false.
• E.g.,
• // Set variables
• var a = new Cq(0, 0, 1);
• var b = new Cq("apple");
• // Define binding
• var binding = CqBind([a,b], function(){ return a.v==1 && b.v=="apple"; },

•  function() {
  

•      // state satisfied, do something. This is the affirmative handler, 
  

•      // which is required.
  

•      window.alert("State satisfied!");
  

•  }, function() {
  

•      // state not satisfied, do nothing. This is the negative handler, 
  

•      // which is optional.
  

•  });
  

• // Satisfy the state, causing the window the pop up.
• a.v = 1;
• // Cleanup
• binding.unbind();
• ////////////////
• Variables are created by newing a Cq object set to a value. The value may
• be of any type. The Cq constructor takes two optional arguments; a min
• value, and a max value. If set, all values outside this inclusive range are
• ignored, and will not trigger handlers. To use them, the value must support

• and < operations.

• The internal connection of the Cq object to the handlers happens via CqBind.
• CqBind takes two mandatory arguments and two arguments that may be undefined.
• It returns a binding which may be destroyed by calling unbind() on it.
• CqBind(varList, testFunc, trueFunc, falseFunc)
• varList is an array of operators for which the binding should watch for
• changes within. If something interesting happens to these variables,
• testFunc is called. If it returns true, then trueFunc is called. If it
• returns false, the falseFunc is called. To call neither, return undefined.
• Within the testFunc, there are four special methods which tell you more
• about the context of your test. <var>.set() tells you if this test is
• being called because <var> was set. <var>.changed() works the same way,
• but is true if the variable was modified. <var>.last() tells you what
• the last value was. The fourth is this.last(), which tells you what this
• test function returned the last time it was called. This is useful for
• instances where you'd like to make sure trueFunc/falseFunc are only called
• when the test value changes, for example.

• API
• OBJECTS
• Cq
• Constructor

•  Cq(value, min=undefined, max=undefined):
  

•      To create a variable that can be used in a state clause, create a Cq 
  

•      object using new.     
  

•      value: initial value of object
  

•      min: optional minimum value object can be set to
  

•      max: optional maximum value object can be set to 
  

• Members

•  v: use to set/get value of Cq object
  

• Methods

•  set90: For use in the test function. Returns true if the test function
  

•      was called because this variable was set.
  

•  changed(): For use in the test function. Returns true if the test function
  

•      was called because this variable was modified.
  

•  last(): For use in the test function. Returns the last value of this 
  

•      variable before the current value.
  

• CqBinding
• Methods

•  last(): For use in the test function, accessed by calling this.last(). 
  

•      Returns the value last returned by this function.
  

•  unbind(): Destroy this binding.
  

• CqSet
• Constructor

•  CqSet():
  

•      Default empty CqSet. A CqSet is a convenience object for organizing
  

•      bindings and cleaning them up quickly.
  

• Members

•  insert(binding): Insert a binding.
  

•  remove(binding): Remove a binding.
  

•  unbind(): Unbind all bindings contained within this CqSet.
  

• FUNCTIONS
• CqBind(varList, testFunc, trueFunc, falseFunc): Return a new CqBinding.

• varList: Array of Cq variable objects.
  

• testFunc: Test that involves the varList variables. Return true to run
  

•     the trueFunc, false for the falseFunc, and undefined for neither.
  

• trueFunc: If testFunc returns true, this is run.
  

• falseFunc: If testFunc returns false, this is run.
  

*/