action_tree 0.1.0

data/.document

@@ -0,0 +1,6 @@
+README.md
+MANUAL.md
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format progress
+spec

data/.yardopts

@@ -0,0 +1,14 @@
+
+
+
+--title "ActionTree"
+
+--protected
+--no-private
+--markup markdown
+--markup-provider maruku
+
+lib/**/*.rb -
+README.md
+MANUAL.md
+LICENSE

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2011 Jostein Berre Eliassen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/MANUAL.md

@@ -0,0 +1,277 @@
+
+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/README.md

@@ -0,0 +1,88 @@
+[**CLICK HERE TO READ THE MANUAL**](http://rdoc.info/github/jbe/action_tree/master/file/MANUAL.md)
+*ALPHA VERSION. Documentation may be out of date.*
+<pre>
+         \/ |    |/
+      \/ / \||/  /_/___/_
+       \/   |/ \/
+  _\__\_\   |  /_____/_
+         \  | /          /
+__ _-----`  |{,-----------~
+          \ }{
+           }{{     ACTION TREE:
+           }}{
+           {{}     a dry request router/controller
+     , -=-~{ .-^- _
+ejm        `}
+            {
+</pre>
+
+    $ gem install action_tree
+
+Quickstart
+----------
+
+
+The Local Office of Alligators, division of information, subdivision of web2.0 and social media, have drawn a (naive) map for their new alligator web API:
+
+
+    welcome
+    |-- alligators
+    |   |-- list
+    |   |-- create
+    |   `-- (with an id)
+    |      |-- edit
+    |      `-- hug
+
+A map like this not only shows paths, but also relationships between actions. For instance, `edit` and `hug` retrieve a specific alligator (with an id) before doing anything else. Similarly, every request beneath `/alligators/` should be counted, to see if we're on Digg yet.
+
+So let's put those two in `before` hooks in an ActionTree:
+
+    routes = ActionTree.new do
+      action { "Welcome to the alligator manager #{@name}!" }
+
+      with 'alligators' do
+        before { @count = (@count || 0) + 1 }
+
+        action            { Alligator.all }
+        action('create')  { Alligator.create }
+
+        with :id do
+          before { @alligator = Alligator.get(@id) }
+          action { 'this is ' + @alligator }
+          action('edit')  { "editing #{@alligator}" }
+          action('hug')   { "#{@alligator} is pleased." }
+        end
+      end
+    end
+
+We can then match and run actions:
+
+    routes.match('/')        #=> #<ActionTree::Match >
+    routes.match('/').found? #=> true
+
+    @name = 'Zap'
+    routes.match('/').run(self) # => "Welcome to the alligator manager, Zap."
+
+    routes.match('/alligators/4').run # => "this is #<Alligator 4>"
+    router.match('/alligators/8/hug').run # => "<#Alligator 8> is pleased."
+
+    routes.match('nonexistant/route') # => #<ActionTree::NotFound>
+    routes.match('nonexistant/route').found? #=> false
+
+
+&nbsp;
+
+
+Available dialects
+------------------
+
+[**at-rack**](https://github.com/jbe/at-rack) turns ActionTree into a Sinatra-like framework, and allows you to mount trees as rack apps.
+
+**at-websocket** is planned to make writing websocket servers easier.
+
+&nbsp;
+
+---
+
+Copyright (c) 2010-2011 Jostein Berre Eliassen. See [LICENSE](http://rdoc.info/github/jbe/action_tree/master/file/LICENSE) for details.
+

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "action_tree"
+    gem.summary = %Q{Versatile routing dry enough to kill cacti.}
+    gem.description = %Q{ActionTree is a router. It provides a compact DSL for defining routes that map paths to actions. It was designed as a router for modern ruby mini-frameworks.}
+    gem.email = "post@jostein.be"
+    gem.homepage = "http://github.com/jbe/action_tree"
+    gem.authors = ["jbe"]
+
+    #gem.required_ruby_version = '>= 1.8.7'
+    gem.add_dependency 'backports'
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+
+task :spec => :check_dependencies
+task :default => :spec
+
+
+
+#namespace :test do
+#  desc 'open testing shell'
+#  task :shell => [:build, :install] do
+#    sh 'irb -r ./test/shell.rb'
+#  end
+#end