### Input, State, Render and Output

There are three pieces to mercury, Input (Controller),
  State (Model) and Render (View).

In a normal mercury app you define your top level Input which
  is a finite list of events.

You then define your top level state "atom". Generally you want
  a large fat state object for your entire application. We then
  wire all the events in Input up to some updating logic, i.e.
  every time an event occurs in Input we do some logic and then
  update the State.

Finally we define our Rendering logic as a single function
  that takes the entire state of our application and returns a
  virtual DOM representation of our UI. Every time the state
  changes we just call render and then update the DOM.

You may also need Output for your application, if we want to 
  have some other side effect other then updating the UI, like
  sending a HTTP POST or writing to a websocket or persisting
  to indexedDB. Then we generally listen to changes in the state
  and have our side effect. Note that Render is just a specific 
  subset of the Output of your application.

### Rendering modules (The view layer)

For the view layer mercury uses a set of modules that come
  together and make it easy to work with a Virtual DOM.

In `mercury` the view is just a function that takes your 
  application state and returns a virtual DOM representation.
  This makes writing your view really easy, you just write it
  top to bottom.

`mercury` then uses the following modules to make it really
  performant to use the virtual DOM to update the real DOM.

#### [`vtree`][vtree]

[`vtree`][vtree] is the module that contains the data 
  structures for the virtual DOM. These are the primitive 
  objects and values that the rendering functions in a 
  mercury app will return.

[`vtree`][vtree] also contains the diffing algorithm used in 
  `mercury`. Mercury uses a diffing algorithm on a virtual DOM 
  to compute a minimal set of `VPatch` records that it can apply to the DOM.

#### [`vdom`][vdom]

[`vdom`][vdom] is the module that contains the `create` and 
  `patch` algorithm for turning the `vtree` data structures 
  into real DOM objects.

[`vdom/create-element`][vdom-create-element] is used to turn a 
  virtual DOM into a real DOM. this is used for the initial 
  rendering of your app.

[`vdom/patch`][vdom-patch] is used to apply a series of `VPatch` 
  records to a real DOM element.

You can also use [`vdom`][vdom] and 
  [`min-document`][min-document] together on the server to 
  generate HTML strings. [`min-document`][min-document] is a 
  minimal fake DOM for use on the server, you can pass 
  [`vdom`][vdom] any `document` you want. In this case 
  [`min-document`][min-document] contains the logic to convert 
  its fake DOM into a HTML string.

#### [`virtual-hyperscript`][virtual-hyperscript]

[`virtual-hyperscript`][virtual-hyperscript] is a module that 
  makes it easier to create `VTree` nodes. It basically exports 
  a `h()` function that creates a DSL similar to `jade` 
  (just more brackets ;)).

[`virtual-hyperscript`][virtual-hyperscript] allows you to write 
  your views in an expressive manner.

#### [`vdom-thunk`][vdom-thunk]

[`vdom-thunk`][vdom-thunk] is a module that increases the 
  performance of building applications with a virtual DOM 
  system. One of the important parts of using a virtual DOM 
  and functional programming in general is to make extensive 
  use of caching.

You can use [`vdom-thunk`][vdom-thunk] to effectively memoize a 
  function that returns a virtual DOM node. This means if you 
  call it twice with the same arguments it will not re-evaluate 
  the function.

This basically means you only have to render that which has 
  changed instead of rendering the entire virtual tree of your
  application.

It should be noted that [`vdom-thunk`][vdom-thunk] assumes 
  arguments are immutable and thus does an O(1) `===` check 
  to see whether the arguments has changed. This will only 
  work if your state is immutable. Thankfully, 
  [`observ-struct`][observ-struct] is immutable

#### [`main-loop`][main-loop]

[`main-loop`][main-loop] is another optimization module for a 
  virtual DOM system. Normally you would re-create the virtual 
  tree every time your state changes. This is not optimum, 
  with [`main-loop`][main-loop] you will only update your 
  virtual tree at most once per request animation frame.

[`main-loop`][main-loop] basically gives you batching of your 
  virtual DOM changes, which means if you change your model 
  multiple times it will be rendered once asynchronously on 
  the next request animation frame.

### State modules (The model layer)

In `mercury` we use immutable data structure primitives to
  represent our model. Using immutable data structures allows
  you to use the [`vdom-thunk`][vdom-thunk] optimization.

`mercury` uses an observable state representation so that you
  can be notified of any changes.

Generally applications built with mercury will have a single
  top level state "atom". i.e. there is one large state object
  for your application and child components do not have local or
  hidden state. However we can directly embed the state of a
  child component in our top level state "atom" to achieve 
  composition.

#### [`observ`][observ]

[`observ`][observ] is the data structure used for observable 
  data. It allows you to create a value for which you can 
  listen for changes.

[`observ`][observ] also comes with higher order functions 
  like [`observ/computed`][observ-computed] that can be used to 
  create new dependent observables. Generally these computed 
  observables cannot be directly mutated but instead change 
  when they data they rely on changes.

[`observ`][observ] is basically an implementation of the 
  `Signal` type that is normally used in FRP.

#### [`observ-struct`][observ-struct]

[`observ-struct`][observ-struct] is an observable that contains an 
  object with a fixed number of keys. Generally the key-value 
  pairs in [`observ-struct`][observ-struct] are themselves 
  observables. You can change the value of any key in an 
  [`observ-struct`][observ-struct] and the top level object 
  will also change to be a new object with that key changed.

[`observ-struct`][observ-struct] uses shallow extension to ensure 
  that every time the struct changes you get a fresh immutable 
  object.

#### [`observ-array`][observ-array]

[`observ-array`][observ-array] is an observable that contains 
  an array of observables. It's generally recommended that this a
  heterogeneous array. You can change the value of any item in
  the array and the top level array will also change to be a 
  new array.

[`observ-array`][observ-array] uses shallow extension to ensure 
  that every time the array changes (an item changes or an 
  item is added or removed) you get a fresh immutable array.

[`observ-array`][observ-array] has the benefit of being able 
  to add or remove items from the array, where as 
  [`observ-struct`][observ-struct] has a fixed number
  of keys and you cannot add more keys to an 
  [`observ-struct`][observ-struct]

### Input modules (The controller layer)

In `mercury` we model all the inputs to our application
  explicitly. We define an input object that contains a bunch of
  [`geval`][geval] Event instances.

Somewhere else in our application we listen to the Input and
  run some logic and update our state when an event happens.

#### [`geval`][geval]

[`geval`][geval] is our data structure for Events. it gives us 
  a way of listening to events and a way of publishing them.

Most of the time you will either create a computed Event that
  emits events based on some raw source, like winddow scroll
  events or a websocket. Or you can create a mutable Event which
  you pass to the UI renderer so it can emit events for dynamically
  created UI components.

[`geval`][geval] is basically an implementation of the 
  `Event` type that is normally used in FRP.

#### [`dom-delegator`][dom-delegator]

[`dom-delegator`][dom-delegator] is an event delegator that 
  allows you to seperate your event listeners from your 
  event emitters. It sets up global event listeners and 
  allow you to embed event handlers on your virtual DOM 
  elements without having to manage adding or removing 
  actual event listeners.

#### [`value-event`][value-event]

[`value-event`][value-event] allows you to create event 
  handlers that you can embed in a virtual DOM. 
  These event handlers work with both the native DOM and 
  [`dom-delegator`][dom-delegator].

[`value-event`][value-event] contains a set of higher order 
  functions that allows you to write to a value to a 
  [`geval`][geval] Event when some user interaction occurs.

Using the higher order functions defined in 
  [`value-event`][value-event] (change, submit, etc. ) 
  allows you to not have to write any DOM event handling 
  code in your application. [`value-event`][value-event]
  takes care of all the reading from the DOM.




  [graphics]: https://github.com/Raynos/graphics
  [elm]: https://github.com/elm-lang/Elm
  [react]: https://github.com/facebook/react
  [om]: https://github.com/swannodette/om
  [reflex]: https://github.com/Gozala/reflex
  [backbone]: https://github.com/jashkenas/backbone
  [quiescent]: https://github.com/levand/quiescent
  [virtual-dom]: https://github.com/Matt-Esch/virtual-dom
  [vtree]: https://github.com/Matt-Esch/virtual-dom/tree/master/vtree
  [vdom]: https://github.com/Matt-Esch/virtual-dom/tree/master/vdom
  [vdom-create-element]: https://github.com/Matt-Esch/virtual-dom/blob/master/vdom/create-element.js
  [vdom-patch]: https://github.com/Matt-Esch/virtual-dom/blob/master/vdom/patch.js
  [min-document]: https://github.com/Raynos/min-document
  [virtual-hyperscript]: https://github.com/Matt-Esch/virtual-dom/tree/master/virtual-hyperscript
  [main-loop]: https://github.com/Raynos/main-loop
  [vdom-thunk]: https://github.com/Raynos/vdom-thunk
  [observ]: https://github.com/Raynos/observ
  [observ-computed]: https://github.com/Raynos/observ/blob/master/computed.js
  [observ-struct]: https://github.com/Raynos/observ-struct
  [observ-array]: https://github.com/Raynos/observ-array
  [geval]: https://github.com/Raynos/geval
  [dom-delegator]: https://github.com/Raynos/dom-delegator
  [value-event]: https://github.com/Raynos/value-event