<commit_before>
> In a rush? You can skip this tutorial page on a first pass. <br>
> It is quite abstract and it won't directly help you write re-frame code. 
> On the other hand, it will considerably deepen your understanding 
> of what re-frame is about, so remember to cycle back and read it later.<br>
> Next page: [Effectful Handlers](EffectfulHandlers.md)

## Mental Model Omnibus

<img height="450px" align="right" src="/images/mental-model-omnibus.jpg?raw=true">

> All models are wrong, but some are useful

The re-frame tutorials initially focus on the **domino
narrative**. The goal is to efficiently explain the mechanics of re-frame,
and to get you reading and writing code ASAP.

But **there are other perspectives** on re-frame
which will deepen your understanding.

This tutorial is a tour of these ideas, justifications and insights.  
It is a little rambling, but I'm hoping it will deliver for you
at least one "Aaaah, I see" moment before the end.

> If a factory is torn down but the rationality which produced it is
left standing, then that rationality will simply produce another
factory. If a revolution destroys a government, but the systematic
patterns of thought that produced that government are left intact,
then those patterns will repeat themselves. <br>
> -- <NAME>, Zen and the Art of Motorcycle Maintenance


## What is the problem?

First, we decided to build our SPA apps with ClojureScript, then we
chose [Reagent], then we had a problem. It was mid 2014.

For all its considerable brilliance,  Reagent (+ React)
delivers only the 'V' part of a traditional MVC framework.

But apps involve much more than V. We build quite complicated
SPAs which can run to 50K lines of code. So, I wanted to know:
where does the control logic go? How is state stored & manipulated? etc.

We read up on [Pedestal App], [Flux],
[Hoplon], [Om], early [Elm], etc., and re-frame is the architecture that
emerged.  Since then, we've tried to keep an eye on further developments like the
Elm Architecture, Om.Next, BEST, Cycle.js, Redux, etc.  They have taught us much
although we have often made different choices.

re-frame does have parts which correspond to M, V, and C, but they aren't objects.
It is sufficiently different in nature
from (traditional, Smalltalk) MVC that calling it MVC would be confusing.  I'd
love an alternative.

Perhaps it is a RAVES framework - Reactive-Atom Views Event
Subscription framework (I love the smell of acronym in the morning).

Or, if we distill to pure essence, `DDATWD` - Derived Data All The Way Down.

*TODO:* get acronym down to 3 chars! Get an image of stacked Turtles for `DDATWD`
insider's joke, conference T-Shirt.

## Guiding Philosophy

__First__, above all, we believe in the one true [<NAME>], creator of Reagent, and
his divine instrument: the `ratom`.  We genuflect towards Sweden once a day.

__Second__, we believe in ClojureScript, immutable data and the process of building
a system out of pure functions.

__Third__, we believe in the primacy of data, for the reasons described in
the main README. re-frame has a data oriented, functional architecture.

__Fourth__, we believe that Reactive Programming is one honking good idea.
How did we ever live without it? It is a quite beautiful solution to one half of re-frame's
data conveyance needs, **but** we're cautious about taking it too far - as far as, say, cycle.js.
It doesn't take over everything in re-frame - it just does part of the job.

__Finally__, a long time ago in a galaxy far far away, I was lucky enough to program in Eiffel
where I was exposed to the idea of [command-query separation](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation).
The modern rendering of this idea is CQRS ([see resources here](http://www.baeldung.com/cqrs-event-sourced-architecture-resources)).
But, even today, we still see read/write `cursors` and two-way data binding being promoted as a good thing.
Please, just say no. We already know where that goes. As your programs get bigger, the use of these two-way constructs
will encourage control logic into all the
wrong places and you'll end up with a tire-fire of an Architecture. <br>
Sincerely, The Self-appointed President of the Cursor Skeptic's Society.

## On DSLs and Machines 

`Events` are cardinal to re-frame - they're a fundamental organising principle. 

Every re-frame app will have a different set of `events` and your job is
to design exactly the right ones for any given app you build. These `events` 
will be the "language of the system". They'll represent "intent" - 
generally the user's. They'll provide the eloquence.

And they are data.

Imagine we created a drawing application. And then we allowed 
someone to use our application, and as they did we captured, into a collection, 
the events caused by that user's actions (button clicks, drags, etc).
 
The collection of events might look like this:  
```cljs
(def collected-events
  [
     [:clear]
     [:new :triangle 1 2 3]
     [:select-object 23]
     [:delete-selected]
     ....
  ])
```

Now, consider the following assembly instructions:
```asm
mov eax, ebx
sub eax, 216
mov BYTE PTR [ebx], 2
```

Assembly instructions are data, right?  Data which happens to be "executable" 
by the right machine - an x86 machine in the case above.

I'd like you to now look back at that collection of events and view it in the 
same way - data which can be executed - by the right machine.

Wait. What machine?  Well, the Event Handlers you register collectively implement 
the "machine" on which these instructions execute. 

In this repo's README, near the top, I explained that re-frame had a 
Data Oriented Design. Typically, that claim means there's a DSL (Domain specific language) 
involved and an interpreter for it.  As you design your re-frame app, 
YOU design a DSL and then YOU provide the machine to execute it.

Summary: 
  - Events are the assembly language of your app. 
  - The instructions collectively form a Domain Specific Language (DSL). The language of your system.
  - These instructions are data. 
  - One instruction after another gets executed by your functioning app.
  - The Event Handlers you register collectively implement the "machine" on which this DSL executes. <commit_msg>Omnibus<commit_after>
> In a rush? You can skip this tutorial page on a first pass. <br>
> It is quite abstract and it won't directly help you write re-frame code. 
> On the other hand, it will considerably deepen your understanding 
> of what re-frame is about, so remember to cycle back and read it later.<br>
> Next page: [Effectful Handlers](EffectfulHandlers.md)

## Mental Model Omnibus

<img height="450px" align="right" src="/images/mental-model-omnibus.jpg?raw=true">

> All models are wrong, but some are useful

The re-frame tutorials initially focus on the **domino
narrative**. The goal is to efficiently explain the mechanics of re-frame,
and to get you reading and writing code ASAP.

But **there are other perspectives** on re-frame
which will deepen your understanding.

This tutorial is a tour of these ideas, justifications and insights.  
It is a little rambling, but I'm hoping it will deliver for you
at least one "Aaaah, I see" moment before the end.

> If a factory is torn down but the rationality which produced it is
left standing, then that rationality will simply produce another
factory. If a revolution destroys a government, but the systematic
patterns of thought that produced that government are left intact,
then those patterns will repeat themselves. <br>
> -- <NAME>irsig, Zen and the Art of Motorcycle Maintenance


## What is the problem?

First, we decided to build our SPA apps with ClojureScript, then we
chose [Reagent], then we had a problem. It was mid 2014.

For all its considerable brilliance,  Reagent (+ React)
delivers only the 'V' part of a traditional MVC framework.

But apps involve much more than V. We build quite complicated
SPAs which can run to 50K lines of code. So, I wanted to know:
where does the control logic go? How is state stored & manipulated? etc.

We read up on [Pedestal App], [Flux],
[Hoplon], [Om], early [Elm], etc., and re-frame is the architecture that
emerged.  Since then, we've tried to keep an eye on further developments like the
Elm Architecture, Om.Next, BEST, Cycle.js, Redux, etc.  They have taught us much
although we have often made different choices.

re-frame does have parts which correspond to M, V, and C, but they aren't objects.
It is sufficiently different in nature
from (traditional, Smalltalk) MVC that calling it MVC would be confusing.  I'd
love an alternative.

Perhaps it is a RAVES framework - Reactive-Atom Views Event
Subscription framework (I love the smell of acronym in the morning).

Or, if we distill to pure essence, `DDATWD` - Derived Data All The Way Down.

*TODO:* get acronym down to 3 chars! Get an image of stacked Turtles for `DDATWD`
insider's joke, conference T-Shirt.

## Guiding Philosophy

__First__, above all, we believe in the one true [Dan Holmsand], creator of Reagent, and
his divine instrument: the `ratom`.  We genuflect towards Sweden once a day.

__Second__, we believe in ClojureScript, immutable data and the process of building
a system out of pure functions.

__Third__, we believe in the primacy of data, for the reasons described in
the main README. re-frame has a data oriented, functional architecture.

__Fourth__, we believe that Reactive Programming is one honking good idea.
How did we ever live without it? It is a quite beautiful solution to one half of re-frame's
data conveyance needs, **but** we're cautious about taking it too far - as far as, say, cycle.js.
It doesn't take over everything in re-frame - it just does part of the job.

__Finally__, a long time ago in a galaxy far far away, I was lucky enough to program in Eiffel
where I was exposed to the idea of [command-query separation](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation).
The modern rendering of this idea is CQRS ([see resources here](http://www.baeldung.com/cqrs-event-sourced-architecture-resources)).
But, even today, we still see read/write `cursors` and two-way data binding being promoted as a good thing.
Please, just say no. We already know where that goes. As your programs get bigger, the use of these two-way constructs
will encourage control logic into all the
wrong places and you'll end up with a tire-fire of an Architecture. <br>
Sincerely, The Self-appointed President of the Cursor Skeptic's Society.

## On DSLs and Machines 

`Events` are cardinal to re-frame - they're a fundamental organising principle. 

Each re-frame app will have a different set of `events` and your job is
to design exactly the right ones for any given app you build. These `events` 
will model "intent" - generally the user's.  They will be the 
"language of the system" and will provide the eloquence.

And they are data.

Imagine we created a drawing application. And then we allowed 
someone to use our application, and as they did we captured, into a collection, 
the events caused by that user's actions (button clicks, drags, key presses, etc).
 
The collection of events might look like this:  
```cljs
(def collected-events
  [
     [:clear]
     [:new :triangle 1 2 3]
     [:select-object 23]
     [:rename "a better name"]
     [:delete-selection]
     ....
  ])
```

Now, consider the following assembly instructions:
```asm
mov eax, ebx
sub eax, 216
mov BYTE PTR [ebx], 2
```

Assembly instructions are represented as data, right?  Data which happens to be "executable" 
by the right machine - an x86 machine in the case above.

I'd like you to now look back at that collection of events and view it in the 
same way - data instructions which can be executed - by the right machine.

Wait. What machine?  Well, the Event Handlers you register collectively implement 
the "machine" on which these instructions execute. When you register a new event handler, 
it is like you are adding to the instruction set of the "machine".

In this repo's README, near the top, I explained that re-frame had a 
Data Oriented Design. Typically, that claim means there's a DSL (Domain specific language) 
involved and an interpreter for it.  As you design your re-frame app, 
YOU design a DSL and then YOU provide the machine to execute it.

Summary: 
  - Events are the assembly language of your app. 
  - The instructions collectively form a Domain Specific Language (DSL). The language of your system.
  - These instructions are data. 
  - One instruction after another gets executed by your functioning app.
  - The Event Handlers you register collectively implement the "machine" on which this DSL executes. 
{'fraction_non_alphanumeric': 0.06319848890288053, 'fraction_numerical': 0.004092554698567606, 'mean_word_length': 4.064567556795536, 'pattern_counts': {'":': 0, '<': 16, '<?xml version=': 0, '>': 32, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5687809', 'n_tokens_mistral': 3608, 'n_tokens_neox': 3372, 'n_words': 1962}