write the flow docs

Author: leafo

docs/actions.md

@@ -1050,9 +1050,11 @@ $options_table{
 
 ### `request:flow(module_name)`
 
-Loads a flow by `module_name` with the `flows_prefix` on the current request
-object. If the flow with that name has been previously loaded, the existing
-flow instance is returned.
+Loads a [Flow]($root/reference/flows.html) by `module_name` with the
+`flows_prefix` on the current request object. If the flow with that name has
+been previously loaded, the existing flow instance is returned. See the [Flows
+guide]($root/reference/flows.html) for more information about using flows to
+organize your application.
 
 ### `request:html(fn)`
 

docs/flows.md

@@ -16,42 +16,85 @@ and field reads and assignments back to the contained object.
 If this explanation is confusing, don't worry. It's easier to understand a flow
 in example. We'll use the `Flow` class standalone to demonstrate how it works.
 
-```lua
--- todo
-```
-
-```moon
+$dual_code{
+lua = [[
+local Flow = require("lapis.flow").Flow
+
+local FormatterFlow = Flow:extend({
+  format_name = function(self)
+    -- self.name and self.age are read from the contained object
+    return self.name .. " (age: " .. self.age .. ")"
+  end,
+
+  print_greeting = function(self)
+    -- self:get_greeting() calls get_greeting on the contained object
+    print(self:get_greeting())
+  end
+})
+]],
+moon = [[
 import Flow from require "lapis.flow"
 
 class FormatterFlow extends Flow
   format_name: =>
+    -- @name and @age are read from the contained object
     "#{@name} (age: #{@age})"
 
-```
+  print_greeting: =>
+    -- @get_greeting! calls get_greeting on the contained object
+    print @get_greeting!
+]]
+}
 
 The above flow provides a `format_name` method that reads the `name` and `age`
-fields. We can instantiate a flow with an object that provides those fields,
-then call that method on the flow instance:
-
-```lua
--- todo
-```
+fields from the contained object. When you access a field or call a method on
+`self` that doesn't exist on the flow, it is automatically proxied to the
+contained object. When calling a method on the contained object, the receiver
+is the contained object itself, not the flow.
+
+We can instantiate a flow with an object that provides those fields, then call
+the flow's method on the flow instance:
+
+$dual_code{
+lua = [[
+local obj = {
+  name = "Pizza Zone",
+  age = "2000 Years",
+  get_greeting = function(self)
+    -- self will always be obj, not a flow instance, even if called through a
+    -- flow
+    return "Hello from " .. self.name
+  end
+}
 
-```moon
+local flow = FormatterFlow(obj)
+print(flow:format_name()) --> "Pizza Zone (age: 2000 Years)"
+flow:print_greeting()     --> "Hello from Pizza Zone"
+]],
+moon = [[
 obj = {
   name: "Pizza Zone"
   age: "2000 Years"
+  get_greeting: =>
+    -- @ will always be obj, not a flow instance, even if called through a
+    -- flow
+    "Hello from #{@name}"
 }
 
-print FormatterFlow(obj)\format_name!
-```
+flow = FormatterFlow(obj)
+print flow\format_name! --> "Pizza Zone (age: 2000 Years)"
+flow\print_greeting!    --> "Hello from Pizza Zone"
+]]
+}
 
-You can think of a flow of a collection of methods that are designed to operate
+You can think of a flow as a collection of methods that are designed to operate
 on a certain kind of object. Why would we use a flow instead of just making
-these methods part of the objects class? A flow lets you encapsulate logic into
-a separate namespace. Instead of having classes with many methods, you split
-apart your methods into flows and leave the class with a smaller
-implementation.
+these methods part of the object's class? A flow lets you encapsulate logic
+into a separate namespace. Instead of having classes with many methods, you
+split apart your methods into flows and leave the class with a smaller
+implementation. This can help your code stay more organized and also make it
+easier to unit-test individual code paths without having to mock and entire
+request.
 
 ## Assigning Fields Within a Flow
 
@@ -63,89 +106,226 @@ If you want assignments on `self` to be sent back to the original class then
 you can use `expose_assigns`. It's a class property that tells the flow how to
 handle assignments to self.
 
-`expose_assigns` can take two types of values: 
+`expose_assigns` can take two types of values:
 
 * `true` -- all assignments are proxied back to the contained object
 * An array of strings -- any field name contained in this array is proxied back to the object
 
+Here's an example using an array to selectively expose certain fields:
+
+$dual_code{
+lua = [[
+local Flow = require("lapis.flow").Flow
+
+local MyFlow = Flow:extend({
+  expose_assigns = {"user", "session"},
+
+  setup = function(self)
+    self.user = fetch_user()      -- proxied to contained object
+    self.session = get_session()  -- proxied to contained object
+    self.cache = {}               -- stored on flow instance (private)
+  end
+})
+]],
+moon = [[
+import Flow from require "lapis.flow"
+
+class MyFlow extends Flow
+  @expose_assigns: {"user", "session"}
+
+  setup: =>
+    @user = fetch_user!      -- proxied to contained object
+    @session = get_session!  -- proxied to contained object
+    @cache = {}              -- stored on flow instance (private)
+]]
+}
+
+This pattern is helpful when you have a Flow operating on a Lapis Request
+object where you want to set up fields on the request that may be made
+available to views or other parts of the request handler.
+
 ## Accessing The Contained Object
 
-The contained object is stored on `self` with the name `_` (an underscore). You
-should avoid writing to this field since the flow expects it to exist.
+The contained object is stored on `self` with the name `_` (an underscore).
+Consider it a reserved field for the flow to operate correctly, don't replace
+it it, but you can access it.
 
-For example, you can call `tostring` on the contained object like this:
+For example, if you need to access the metatable on the contained object for
+some reason:
 
-```lua
--- todo
-```
+$dual_code{
+lua = [[
+local Flow = require("lapis.flow").Flow
 
-```moon
+local MetatableFlow = Flow:extend({
+  get_metatable = function(self)
+    return getmetatable(self._)
+  end
+})
+
+print(MetatableFlow({}):get_metatable())
+]],
+moon = [[
 import Flow from require "lapis.flow"
 
-class StringFlow extends Flow
-  address: =>
-    tostring @_
+class MetatableFlow extends Flow
+  get_metatable: =>
+    getmetatable @_
 
-print StringFlow({})\address!
-```
+print MetatableFlow({})\get_metatable!
+]]
+}
 
 ## Organizing Your Application With Flows
 
-in lapis, an application class is where you define routes and your request
-logic. since there are so many responsibilities it easy for an applicatoin
-class to get too large to maintain. a good way of separating concerns is to use
+In Lapis, an application class is where you define routes and your request
+logic. Since there are so many responsibilities it's easy for an application
+class to get too large to maintain. A good way of separating concerns is to use
 flows. In this case, the contained object will be the request instance. You'll
 call the flow from within your application. Because this is a common pattern,
 there's a `flow` method on the request object that makes instantiating flows
 easy.
 
-In this example we declare a flow class for handling logging in and registering
-on a website. From our applicaton we call the flow:
-
-```moon
+In this example, we declare a flow class for handling logging in and
+registering on a website. Logging in and registering an account may share code,
+so we can use additional flow methods to encapsulate our logic without
+repeating ourselves.
+
+From our application we call the flow:
+
+$dual_code{
+lua = [[
+local Flow = require("lapis.flow").Flow
+
+local AccountsFlow = Flow:extend({
+  check_params = function(self)
+    -- validate self.params...
+  end,
+
+  write_session = function(self, user)
+    -- store user in session...
+  end,
+
+  login = function(self)
+    self:check_params()
+    -- load user from database...
+    self:write_session(user)
+    return { redirect_to = self:url_for("homepage") }
+  end,
+
+  register = function(self)
+    self:check_params()
+    -- create user in database...
+    self:write_session(user)
+    return { redirect_to = self:url_for("homepage") }
+  end
+})
+]],
+moon = [[
 import Flow from require "lapis.flow"
+
 class AccountsFlow extends Flow
+  check_params: =>
+    -- validate @params...
+
+  write_session: (user) =>
+    -- store user in session...
+
   login: =>
-    -- check parameters
-    -- create the session
-    redirect_to: @url_for("homepage")
+    @check_params!
+    -- load user from database...
+    @write_session user
+    redirect_to: @url_for "homepage"
 
   register: =>
-    -- check parameters
-    -- create the account, or return error
-    -- create a session
-    redirect_to: @url_for("homepage")
-```
+    @check_params!
+    -- create user in database...
+    @write_session user
+    redirect_to: @url_for "homepage"
+]]
+}
 
 The structure of your application could then be:
 
-```moon
+$dual_code{
+lua = [[
+local lapis = require("lapis")
+local capture_errors = require("lapis.application").capture_errors
+
+local app = lapis.Application()
+
+app:match("login", "/login", capture_errors(function(self)
+  return self:flow("accounts"):login()
+end))
+
+app:match("register", "/register", capture_errors(function(self)
+  return self:flow("accounts"):register()
+end))
+]],
+moon = [[
 class App extends lapis.Application
   [login: "/login"]: capture_errors => @flow("accounts")\login!
   [register: "/register"]: capture_errors => @flow("accounts")\register!
-```
+]]
+}
 
 ## Nested Flows
 
-When you instantiate a flow from within a flow, the backing object is wrapped
-directly by the the new flow. This means that the current flow's methods are
-not made available to the new flow.
+When you instantiate a flow and pass an existing flow as the argument, the
+backing object is passed directly into the new flow. This means that the
+current flow's methods are not made available to the new flow.
+
+$dual_code{
+lua = [[
+local Flow = require("lapis.flow").Flow
+
+local my_object = { color = "blue" }
 
-```lua
--- todo
-```
+local FlowA = Flow:extend({})
+local FlowB = Flow:extend({})
 
+local flow_a = FlowA(my_object)
+local flow_b = FlowB(flow_a)  -- passing flow_a, not my_object
+
+-- flow_a and flow_b both point to my_object
+assert(flow_a._ == my_object)
+assert(flow_b._ == my_object)
+]],
+moon = [[
+import Flow from require "lapis.flow"
 
-```moon
 my_object = { color: "blue" }
 
-class SubFlow extends flow
-  check_object: =>
-    assert my_object == @_
+class FlowA extends Flow
+class FlowB extends Flow
+
+flow_a = FlowA my_object
+flow_b = FlowB flow_a  -- passing flow_a, not my_object
+
+-- flow_a and flow_b both point to my_object
+assert(flow_a._ == my_object)
+assert(flow_b._ == my_object)
+]]
+}
 
-class OuterFlow extends flow
-  get_sub: => subflow @
+## Utility Functions
 
-OuterFlow(my_object)\get_sub!\check_object!
-```
+### `is_flow(cls)`
 
+The `is_flow` function checks if a class or instance is a Flow:
+
+$dual_code{
+lua = [[
+local is_flow = require("lapis.flow").is_flow
+
+if is_flow(some_object) then
+  -- handle flow...
+end
+]],
+moon = [[
+import is_flow from require "lapis.flow"
+
+if is_flow some_object
+  -- handle flow...
+]]
+}