Permalink
Browse files

readme update

  • Loading branch information...
1 parent 585ca67 commit 5b05302c3e75cf929bb4dad79c356da8f81dcac6 @vogievetsky committed Sep 2, 2012
Showing with 94 additions and 56 deletions.
  1. +94 −56 README.md
View
150 README.md
@@ -1,99 +1,137 @@
# DVL
-**DVL** is a free functionally reactive library written in JavaScript. DVL is based on the idea that data, not control flow is the most importnatn aspect of a program focused on data visulaization.
+**DVL** is a free functionally reactive library written in JavaScript. DVL is based on the idea that data, not control flow is the most important aspect of a program focused on data visualization.
DVL is built on top of [D3](http://mbostock.github.com/d3/) to allow for dynamic data binding to the DOM.
## Usage
The code DVL functionality can be described with the following functions:
-**dvl.def**
+**dvl**
-Creates a wrapped variable that can dispatch events.
+Creates a DVL variable with the given initial value. A DVL variable's value can be read and set. When the value is updated it will automatically notify any code that depends on it.
- var x = dvl(5);
- x.get(); //== 5
- x.set(7);
- x.get(); //== 7
- x.notify();
+```javascript
+var x = dvl(5);
+console.log(x.value()); //=> 5
+x.value(7);
+console.log(x.value()); //=> 7
+```
-The above example creates a wrapped DVL variable with an initial value of 5. This value can be modified through x.get() and x.set(7). To announce to the rest of the program that x has changed x.notify() can be called.
+A DVL variable can take any value that a regular JavaScrip variable can take with the exception of `undefined` since through the virtue of being created a DVL variable is always defined. Setting the value of a DVL variable to `undefined` will cause it to be `null`.
-The null value is used to mark that a variable is invalid.
+```javascript
+console.log(dvl().value()); //=> null
+console.log(dvl(null).value()); //=> null
+console.log(dvl(undefined).value()); //=> null
+console.log(dvl(5).value(undefined).value()); //=> null
+```
-**dvl.register**
+A DVL variable is considered invalid if its value is set to `null`. It is perfectly fine to have variables in an invalid state but some functions will treat invalid variables as a special case.
-Registers a function to be called whenever any of the registered listened to objects change as well as announcing what objects the function might modify.
-
- var a = dvl(5);
- var b = dvl(12);
- var c = dvl(null);
-
- function calc() {
- var av = a.get();
- var bv = b.get();
- if (av !== null && bv !== null) {
- c.set(Math.sqrt(av*av + bv*bv));
- c.notify();
- } else {
- c.set(null);
- c.notify();
- }
- }
+**dvl.apply**
- dvl.register({
- fn: calc,
- listen: [a, b],
- change: [c]
- });
+One of the most useful functions in DVL the apply function creates a new DVL variable the value of which tracks the result of the given function as applied to the supplied parameters.
- c.get() //== 13
+```javascript
+var a = dvl(5);
+var b = dvl(12);
- a.set(3).notify()
- b.set(4).notify()
- c.get() //== 5
+var c = dvl.apply([a, b], function(_a, _b) {
+ return Math.sqrt(_a * _a + _b * _b);
+});
-The above example ensures that calc will be run when a or b change, updating c.
+console.log(c.value()) //=> 13
-We must explicitly declare that calc will be changing c. This is important for DVL to calculate the dependency graph and ensure that it is acyclic. Modifying a variable without specifying that it might be modified will raise an error.
+a.value(3)
+console.log(c.value()) //=> 12.36931687685298
-**dvl.apply**
+b.value(4)
+console.log(c.value()) //=> 5
+```
-The apply function is a short-form for simplifying a common pattern found in DVL.
+The 'worker function' in the apply gets called with the actual values of the variables.
- var a = dvl(5);
- var b = dvl(12);
+_Note: The suggested convention is to name the 'value parameters' with a leading underscore to aid readability by visually separating the DVL variable form it's actual value. This convention is adopted here._
- var c = dvl.apply(
- [a, b],
- function(av, bv) { return Math.sqrt(av*av + bv*bv); }
- );
+If any of the arguments to a DVL apply function are invalid (value of `null`) then the 'worker function' will not be called and instead the result will be set to invalid.
- c.get() //== 13
+```javascript
+b.value(null)
+console.log(c.value()) //=> null
- a.set(3).notify()
- b.set(4).notify()
- c.get() //== 5
+b.value(4)
+console.log(c.value()) //=> 5
+```
-The above example is equivalent to the example given for dvl.register.
+**dvl.applyAlways**
-## Credits
+Auto invalidation is often the desired behavior and a convenience since the arguments within the 'worker function' will never be null, but sometimes it does make scenes for the result of the apply to be something valid even if some of the arguments are invalid.
-[Vadim Ogievetsky](http://vadim.ogievetsky.com)
+```javascript
+var who = dvl('Jason');
+var what = dvl('cake');
-[Barret Schloerke](http://github.com/schloerke)
+var likes = dvl.applyAlways([who, what], function(_who, _what) {
+ if (_who === null) {
+ return null; // Deal with the case of not having a 'who', set likes to invalid.
+ }
+ return _who + (_what === null ? ' does not like anything.' : ' likes ' + _what + '!');
+});
-With invaluable advice from [Mike Bostock](http://bost.ocks.org/mike/)
+console.log(likes.value()) //=> 'Jason likes cake!'
+what.value('flying')
+console.log(likes.value()) //=> 'Jason likes flying!'
+what.value(null)
+console.log(likes.value()) //=> 'Jason does not like anything.'
+who.value(null)
+console.log(likes.value()) //=> null
+```
+**dvl.register**
+Registers a low level function that registers a function to be called reactively when a DVL variable changes. The `apply` and `applyAlways` functions are just convenience wrappers around a register.
+
+```javascript
+var a = dvl(5);
+var b = dvl(12);
+var c = dvl();
+
+dvl.register({
+ listen: [a, b],
+ change: [c],
+ fn: function() {
+ var _a = a.value();
+ var _b = b.value();
+ if (_a !== null && _b !== null) {
+ c.value(Math.sqrt(_a * _a + _b * _b));
+ } else {
+ c.value(null);
+ }
+ }
+});
+
+console.log(c.value()); //=> 13
+
+a.value(3);
+b.value(4);
+console.log(c.value()); //=> 5
+```
+
+The above example is equvelant to the first `dvl.apply` example.
+We must explicitly declare that the function being registered will be changing `c`. This is important for DVL to calculate the dependency graph and ensure that it is acyclic. Modifying a variable without specifying that it might be modified will throw an error.
+## Credits
+[Vadim Ogievetsky](http://vadim.ogievetsky.com)
+[Barret Schloerke](http://github.com/schloerke)
+With invaluable advice from [Mike Bostock](http://bost.ocks.org/mike/)

0 comments on commit 5b05302

Please sign in to comment.