Browse files


  • Loading branch information...
0 parents commit f4770dd5b1b97acc3372329c610fc5d5d3b72e05 @alandipert alandipert committed Feb 15, 2013
@@ -0,0 +1,15 @@
@@ -0,0 +1,3 @@
+language: clojure
+lein: lein2
+script: lein2 cljsbuild test
@@ -0,0 +1,129 @@
+# Javelin
+<img src=""
+alt="tailrecursion/javelin logo" title="tailrecursion/javelin logo"
+align="right" width="152"/>
+Spreadsheet-like Functional Reactive Programming (FRP) in
+ClojureScript. This library is usable but under construction and
+subject to frequent change.
+### Example
+(ns your-ns
+ (:require tailrecursion.javelin) ;; necessary if compiling in advanced mode
+ (:require-macros [tailrecursion.javelin.macros :refer [cell]]))
+(defn start []
+ (let [a (cell 0) ;; value cell of 0.
+ b (cell (inc a)) ;; formula cell of a+1.
+ c (cell (+ 123 a b))] ;; formula cell of a+b+123.
+ (cell (.log js/console c))
+ ;; c's initial value, 124, is printed.
+ (swap! a inc)
+ ;; a was incremented, and its new value propagated (consistently)
+ ;; through b and c. c's new value, 126, is printed to the console.
+ ))
+### Dependency
+[tailrecursion/javelin "1.0.0-SNAPSHOT"]
+### Demos
+For more usage examples, see the [Javelin
+Demos]( repository.
+You may see some version of the demos running at
+## Overview
+Javelin provides a spreadsheet-like computing environment consisting
+of **cells**, **values**, and **formulas**. Cells are similar to
+Clojure atoms: they contain values, they can be dereferenced with
+`deref` or the `@` reader macro, and their contents are mutated using
+the `swap!` and `reset!` core functions. Formulas are ClojureScript
+expressions that may contain references to cells.
+### Input Cells and Formula Cells
+**Input cells** contain values that are updated explicitly using
+`reset!` or `swap!`. **Formula cells** contain values that are
+recomputed by Javelin whenever the values in the cells referenced in
+the formula expression are changed.
+Both kinds of cell are created with the Javelin `cell` macro. It
+expects a single argument. If the argument is a number, string,
+keyword, anonymous function, or quoted expression the cell will be an
+input cell. Otherwise, the new cell will be a formula cell.
+(def a (cell 42)) ;; input cell containing the value 42
+(def b (cell '(+ 1 2))) ;; input cell containing the value 3
+(def c (cell (+ a 1))) ;; formula cell containing the value a+1, updated when a changes
+(reset! a 7) ;; update the value contained by the input cell explicitly
+(swap! c inc) ;; no! c is a formula cell; it updates itself!
+### Formulas
+Formula cells may refer to themselves with the `~value` idiom, where
+`value` is the initial value to use (the cell has no "self" value
+before it has evaluated itself the first time). Self references refer
+to the value in the cell prior to updating, of course.
+(let [a (cell 0) ;; input cell
+ b (cell (conj ~[] a))] ;; formula cell w/ self reference, ~[]
+ (cell (.log js/console (pr-str b)))
+ ;; [0] is printed first
+ (swap! a inc)
+ (swap! a inc)
+ ;; then [0 1] and [0 1 2] are printed
+ )
+### Continuous vs. Discrete Propagation
+Normally, if the value contained by a cell does not change, nothing
+happens. For instance, `(swap! c identity)` has no effect on input
+cell `c`'s dependents, if any. This behavior, the default, is known as
+**continuous propagation**.
+The `all!` function can be used to mutate a cell and turn on
+**discrete propagation**. All updates will then trigger
+propagation. The `distinct!` function turns off discrete
+propagation. If a formula references a cell that is in discrete
+propagation mode, the dependent formula cell is also put in discrete
+(def a (cell 0))
+(def b (cell (.log js/console a)))
+(all! a) ;; turn on discrete propagation
+(reset! a 0) ;; 0 is printed in the console
+(reset! a 0) ;; 0 is printed in the console again
+(distinct! a) ;; turn off discrete propagation
+(reset! a 0) ;; nothing happens
+## License
+ Copyright (c) Alan Dipert and Micha Niskin. All rights
+ reserved. The use and distribution terms for this software are
+ covered by the Eclipse Public License 1.0
+ ( which can be
+ found in the file epl-v10.html at the root of this
+ distribution. By using this software in any fashion, you are
+ agreeing to be bound by the terms of this license. You must not
+ remove this notice, or any other, from this software.
Oops, something went wrong.

0 comments on commit f4770dd

Please sign in to comment.