action_tree 0.1.1 → 0.2.0

data/MANUAL.md

@@ -1,277 +0,0 @@
-
-ActionTree
-==========
-
-**Manual pages**
-
-<pre>
-         \/ |    |/
-      \/ / \||/  /_/___/_
-       \/   |/ \/
-  _\__\_\   |  /_____/_
-         \  | /          /
-__ _-----`  |{,-----------~
-          \ }{
-           }{{     ACTION TREE:
-           }}{
-           {{}     a dry request router/controller
-     , -=-~{ .-^- _
-ejm        `}
-            {
-</pre>
-
-This document covers:
-
-1.  Architecture
-2.  Usage
-    1.  Defining routes
-    2.  Looking up requests
-    3.  Running match results
-3.  Dialects
-4.  Advanced usage
-    1.  Modularity
-    2.  Recursive routes
-
-
-&nbsp;
-
-Architecture
-------------
-
-ActionTree is a [DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself) request router/controller framweork suitable for web apps. Given a request, such as `/houses/21/parties`, it runs the relevant pieces of code in the right order, with the right variables.  It is a bit similar to [Sinatra](http://www.sinatrarb.com/)'s routing, in that it maps URLs to procs, but is much more powerful.
-
-The routes are kept as a tree of nodes. Request paths are looked up through the tree in the same way that file paths match a file tree. Unlike file trees, one node can match several, and not just one path fragment. In other words, looking up '/house/32/info' first looks for a child node that matches 'house', then from there a child node matching '32', and from there child node matching 'info'.
-
-Each node has:
-
-* A match token
-* N child nodes
-
-Each node also has
-
-* One optional (namespaced) action
-* One optional not_found handler
-* N ordered before filters
-* N ordered after filters
-* N ordered postprocessors
-
-All of these are procs. Everything except the action is inherited by all descending nodes.
-
-Finally, each node has
-
-* A helper scope with n methods, stored as a module.
-
-These helpers are also inherited by all descending nodes.
-
----
-
-Since all routes are trees, all routes can easily be reused or mounted in several locations. Since inheritance happens per request, the same route mounted several places can work differently in each context.
-
-This enables DRY and concise controllers and routes.
-
-Actually, the routes are not even really trees, but graphs, which means you can build infinite, recursive routes, such as `/me/dad/mom/mom/dad/dad/dad/...` -- although that would be a strange thing to do.
-
-
-### Paths and locations
-
-I will differentiate between request *paths* and route *locations*.
-
-**Paths**, like `/houses/21`...
-
-* Express route lookups.
-* Are divided into fragments, like `"21"`, `"bobsleigh"` or `"Tirol"`.
-
-**Locations**, like `houses/:number`...
-
-* Express route definitions.
-* Are divided into tokens, like `:number`, `'about'` or `/[a-z]+/`.
-* Can be
-  * plain: `'about'`
-  * captures:
-    * `:number`,
-    * `':embedded-:symbol'`
-    * `/regex[p]?/`.
-
-
-&nbsp;
-
-Defining routes
----
-
-### DSL Methods
-
-Each of the following DSL methods take an optional location argument and a block parameter. The location format is specified later in this document. If omitted, the location will be the same as the current context.
-
-**route**(location=nil, &blk)
-: Also known as `with`, `r`, `w`, `_`
-: Evaluates the code in `blk` in context of the specified `location`.
-
-**action**(location=nil, layer=nil, &blk)
-: Also known as `a`, `o`
-: Attaches an action. Any number of actions can be attached to every node, and they will run in the same order later. `layer` specifies a layer name, to allow storing different actions for different contexts in the same node.
-
-**get**, **put**, **post** and **delete**
-: Shortcuts to layering actions.
-: These methods are shortcuts to the action method above, to simplify layering of http verbs.
-
-
-**before**(location=nil, &blk)
-: Also known as `b`
-: Attaches another before hook to be run for this action and all descendants.
-
-**after**(location=nil, &blk)
-: Attaches another after hook to be run for this action and all descendants.
-
-**helpers**(location=nil, &blk)
-: Use def inside the block to write helper methods that will be available to all descendants.
-
-**not_found**(location=nil, &blk)
-: Also known as `x`
-: todo
-
-**mount**(node)
-: todo
-
-**mount**(location, node)
-: todo
-
-
-### Location format specification
-
-Locations can be expressed in four ways:
-
-* A single token, such as `"bobsleigh"`, `:variety` or `/[0-9]+/`
-* A path string, such as `"/book/chapter/:page/:from-:to"`
-* An array of tokens, like `["ideas", :id, "search", /[a-z]+/]`
-* Omitting the path parameter, resulting in a reference to the current scope.
-
-There are four different types of tokens:
-
-* `"bobsleigh"` matches the exact path segment "bobsleigh".
-* `:variety` matches any path segment and keeps it as @variety.
-* `/[0-9]+/` matches the regexp, in this case numbers.
-* `":year-:month-:date"` matches "anything-like-this", keeping it as `@year`, `@month` and `@date`
-
-All these can be used with DSL methods, like this:
-
-    before('bobsleigh')   { polish_ice }
-    action(:variety)      { "Thank you for choosing #{@variety}" }
-    after(/[0-9]+/)       { log_number(@match.to_i) }
-    helper(':id-:name')   { Cow.get(@id) }
-    route [/[0-9]+/, /[0-9]+/, /[0-9]+/] do
-      "You visited #{match.join('/')}"
-    end
-
-
-### Utility methods
-
-#### descend
-
-    descend(location) #=> #<ActionTree::Node>
-    
-    house_routes = routes.descend('houses')
-
-Returns the node at `location` relative to the current context.
-
-
-
-&nbsp;
-
-Looking up requests
--------------------
-
-- matching
-  - was it found?
-  - on to run
-  - match chain
-
-
-
-&nbsp;
-
-Running match results
----------------------
-
-- running
-  - parameters: scope and action layer.
-  - scope is created
-    - precedence: captures overwrite source scope.
-    - variable copy
-    - captures
-      - accumulation
-      - regexps accumulate in @match
-    - esoteric variables, such as @__match
-    - dialect variables, such as @get and @post
-  - actions are run
-    - order
-      each node with before hooks -> run in order of attachment
-      actions of current node run in order of attachment
-      each node with after filters -> run in order of attachment
-
-
-
-
-
-
-
-
-&nbsp;
-
-Appendix
---------
-
-### Re-using routes
-
-Let's say we want to make a reusable authentication API:
-
-    simple_auth = ActionTree.new do
-      before { authenticate }
-      action('login')   { ... }
-      action('logout')  { ... }
-    end
-
-Now this can be mounted anywhere
-
-    some_app = ActionTree.new do
-      # tada:
-      mount simple_auth
-
-      with('cars') do
-        # or within a scope
-        mount instant_storefront
-      end
-
-      # or with a path:
-      mount 'docs/api', magic_api_doc_generator
-    end
-
-If you want to pick out a subsection from routes you have already built, you can use the `descend` method:
-
-    car_routes = some_app.descend('cars')
-
-Now we can mount just the car routes in another ActionTree, or even somewhere else within the same one. We can even make endless circular route constructs...
-
-    family = ActionTree.new do
-      before('father') { @person = @person.father }
-      before('mother') { @person = @person.mother }
-      action('show')   { @person.render }
-    end
-
-    family.mount('father', family)
-    family.mount('mother', family)
-
-    me = ActionTree.new do
-      before { @person = ME }
-      mount family
-    end
-
-    me.match('mother/father/mother/father/father/father').run # => great-great-grand-whatnot
-
-
-
-
-### DSL variants ###
-
-### Mounting and advanced routes ###
-
-

data/lib/action_tree/basic/match.rb

@@ -1,132 +0,0 @@
-
-
-
-
-class ActionTree::Basic::Match
-
-  include ::ActionTree::DialectHelper
-
-  DEFAULT_HELPERS = []
-
-  attr_reader :node, :selected_scope, :parent, :fragment
-
-  def initialize(node, parent, fragment)
-    @node, @parent, @fragment = node, parent, fragment
-  end
-
-  def found?; @node; end
-
-  def captures
-    @captures ||= read_captures
-  end
-
-  def match_chain
-    @match_chain ||= @parent ? @parent.match_chain << self : [self]
-  end
-
-  def valid_match_chain
-    @valid_match_chain ||= match_chain.select(&:node)
-  end
-
-  def node_chain
-    @node_chain ||= valid_match_chain.map(&:node)
-  end
-
-  def path
-    match_chain.map(&:fragment).join('/')
-  end
-
-  # Run the action; first the before filters within the match chain, then the actions, then the postprocessors, then the after filters, returning the return value of the last evaluated action.
-  def run(namespace=:default, *scope_sources)
-
-    eval_scope = ::ActionTree::EvalScope.new(
-      *helper_mixins, *scope_sources, captures,
-      *DEFAULT_HELPERS,
-      {:__match => self}
-      )
-
-    hooks(:before_hooks).each {|prc| eval_scope.instance_eval(&prc) }
-    result = eval_scope.instance_eval(&main_action(namespace))
-    hooks(:after_hooks).each  {|prc| eval_scope.instance_eval(&prc) }
-
-    postprocessors.inject(result) do |result, postprocessor|
-      eval_scope.instance_exec(result, &postprocessor)
-    end
-  end
-
-
-  # Return @self@ or a descendant matching @path@, or a {NotFound} if not found.
-  def match(path)
-    path = parse_path(path)
-    return self if path.empty?
-    return self unless found?
-
-    fragment = path.shift
-    @node.children.each do |child|
-      if child.match?(fragment)
-        return self.class.new(
-          child, self, fragment).match(path)
-      end
-    end
-
-    self.class.new(nil, self, fragment) # not found
-  end
-
-  private
-    def parse_path(path)
-      case path
-        when Array then path
-        else path.to_s.gsub(/(^\/)|(\/$)/, '').split('/')
-      end
-    end
-
-    def not_found_handler
-      node_chain.reverse.each do |node|
-        return node.not_found_handler if node.not_found_handler
-      end; nil
-    end
-
-    def read_captures
-      hsh = ::ActionTree::CaptureHash.new
-
-      match_chain[1..-1].each do |m|
-        if m.found? && m.node.capture_names.any?
-          raw_captures = m.fragment.match(m.node.regexp).captures
-          m.node.capture_names.each_with_index do |name, i|
-            hsh.add(name, raw_captures[i])
-          end
-        end
-      end
-      hsh
-    end
-
-    def main_action(namespace)
-      (found? ?
-        @node.action_namespaces[namespace] :
-        not_found_handler
-      ) || Proc.new { nil }
-    end
-
-    def helper_mixins
-      node_chain.map(&:helper_scope)
-    end
-
-    def hooks(type)
-      node_chain.map {|n| n.send(type) }.flatten
-    end
-
-    def postprocessors
-      @node ? @node.postprocessors : []
-    end
-
-    def inherit_via_node_chain(&blk)
-      n = node_chain.reverse.detect(&blk)
-      n ? blk.call(n) : nil
-    end
-
-end
-
-
-
-
-

data/lib/action_tree/dialect_helper.rb

@@ -1,12 +0,0 @@
-
-module ActionTree::DialectHelper
-
-  # access to the dialect namespace
-  def dialect
-    modules = self.class.name.split('::')
-    modules.pop
-    modules.inject(Kernel) do |current, next_const|
-      current.const_get(next_const)
-    end
-  end
-end

data/lib/action_tree/plugins/tilt.rb

@@ -1,65 +0,0 @@
-
-
-
-require 'tilt'
-
-module ActionTree::Plugins::Tilt
-
-  CACHE = Tilt::Cache.new
-
-  module NodeMixin
-    # sets a default, optionally namespaced, layout for this and
-    # descending nodes
-    def layout(path, namespace=nil)
-      layout_namespaces[namespace] = path
-    end
-
-    def layout_namespaces
-      @layout_namespaces ||= {}
-    end
-
-    # sets a default view folder path for this and descending nodes.
-    def view_path(path=nil)
-      path ? @view_path = path : @view_path
-    end
-  end
-
-  module MatchMixin
-    def view_path
-      inherit_via_node_chain(&:view_path) || '.'
-    end
-
-    def layout(namespace=nil)
-      inherit_via_node_chain do |node|
-        node.layout_namespaces[namespace]
-      end
-    end
-  end
-
-
-  module Helpers
-
-    def render(path, layout_namespace=nil, &blk)
-      path = ::File.join(@__match.view_path, path)
-      
-      template = ::ActionTree::Plugins::Tilt::CACHE.fetch(
-        path) { Tilt.new(path, nil, {}) }
-      
-      if respond_to?(:content_type)
-        content_type(template.class.default_mime_type)
-      end
-
-      result = template.render(self, &blk)
-
-      layout = @__match.layout(layout_namespace)
-      if layout && !%w{sass scss less coffee}.include?(File.extname(path))
-        render(layout, :AbSoLuTeLy_No_LaYoUt) { result }
-      else
-        result
-      end
-    end
-
-  end
-
-end
-