action_tree 0.1.1 → 0.2.0

data/.yardopts

@@ -1,6 +1,3 @@
-
-
-
 --title "ActionTree"
 
 --protected
@@ -8,7 +5,8 @@
 --markup markdown
 --markup-provider maruku
 
-lib/**/*.rb -
+--plugin rspec
+
+lib/**/*.rb spec/**/*.rb -
 README.md
-MANUAL.md
 LICENSE

data/README.md

@@ -1,88 +1,17 @@
-[**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
+ActionTree
+==========
 
-Quickstart
-----------
+ActionTree helps you write DRY and concise controller logic. It provides a compact DSL for defining actions and mapping them against the requests that invoke them.
 
+[**Manual**](https://github.com/jbe/action_tree/wiki)
 
-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:
+[**API docs**](http://rubydoc.info/github/jbe/action_tree/master/frames)
 
-
-    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.
+*NB: Alpha stage. Unstable API.*
 
 &nbsp;
 
 ---
 
 Copyright (c) 2010-2011 Jostein Berre Eliassen. See [LICENSE](http://rdoc.info/github/jbe/action_tree/master/file/LICENSE) for details.
-

data/Rakefile

@@ -5,8 +5,8 @@ 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.summary = %Q{Versatile and DRY controllers and routing.}
+    gem.description = %Q{ActionTree is a DRY request router. It provides a compact DSL for defining actions and mapping requests to invoke them.}
     gem.email = "post@jostein.be"
     gem.homepage = "http://github.com/jbe/action_tree"
     gem.authors = ["jbe"]
@@ -14,6 +14,10 @@ begin
     #gem.required_ruby_version = '>= 1.8.7'
     gem.add_dependency 'backports'
 
+    gem.add_development_dependency 'rspec'
+    gem.add_development_dependency 'yard'
+    gem.add_development_dependency 'yard-rspec'
+
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
@@ -31,10 +35,19 @@ end
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  #t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+  #t.options = ['--any', '--extra', '--opts'] # optional
+end
 
 task :spec => :check_dependencies
-task :default => :spec
 
+task :docs => :yard
+
+task :build => :docs
+
+task :default => :spec
 
 
 #namespace :test do

data/TODO

@@ -1,32 +1,90 @@
 
 
 
+porting sinatra
+  code: l 59    
+    HTTP Verb helpers
+    halt(code)
+  specs: l 0
 
-dialect mixins
-  templating
-
-rewrite tests
-tests for:
-  variable scope copy
-  after hooks
-  action namespaces
-  running different action layers
-  get, put, post, delete
-  postprocessors
-  mounting
-  layers & application
-
-
-documentation for:
-  postprocessors
-  action namespaces
-  new mounting
-  layer application
-    ActionTree.layer
-    Node.apply(layer)
-  mounting versus layer application
-  get, put, post, and update helpers
-  DSL shorthands/aliases
-  applying plugins
 
+code:
+  Basic
+    finish documenting Node
+    Give Match a wash
+    document Match
+  Templates
+  raise errors:
+    template not found
+    
+  display errors?
 
+
+documentation
+  Rack
+    use Rack::ShowExceptions for html error pages.
+    `use` belongs in config.ru :)
+
+ideas
+  `at-rack-serve` command-line tool
+
+
+ActionTree spec outline
+=======================
+
+00 Foundations [DONE]
+
+01 Node
+
+  #inspect
+  #printout
+
+  #locate
+
+  - for string, symbol, sinatra-style, nasty
+    sinatra-style regexp, and nasty regexp
+  #match?
+  #capture_names
+  #read_captures
+
+  dsl
+    #route
+    #mount
+      when children have the same name
+    #add_child
+
+02 Match
+
+#run
+  not_found
+  actions
+    namespaces
+    exception handling
+  scope
+    user supplied
+      hash sets instance variables
+      module is extended
+      array is both
+    captures
+      sinatra style
+      regex style
+      accumulate
+
+
+03 ActionTree::Basic
+  scenario with:
+  captures: string, symbol, nasty sinatra-style
+  building
+    using: array paths, regex paths, string paths, symbol paths
+
+  config: inheritance, overwrite
+
+  actions: namespaces, after, before, postprocessors, deep
+
+  fancy: mounting
+
+  run-time: user vars, priority, @config
+
+04 Components
+  tilt
+  http verb

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/action_tree.rb

@@ -1,45 +1,64 @@
 
+#
+#           \/ |    |/
+#        \/ / \||/  /_/___/_
+#         \/   |/ \/
+#    _\__\_\   |  /_____/_
+#           \  | /          /
+#  __ _-----`  |{,-----------~
+#            \ }{
+#             }{{
+#             }}{       ActionTree (c) 2011
+#             {{}       Jostein Berre Eliassen
+#       , -=-~{ .-^- _
+#  ejm        `}
+#              {
+#
+
 require 'set'
 require 'backports'
 
+# The main ActionTree namespace. Provides convenient
+# shortcuts to common operations. Contains utility classes
+# and dialect modules. For more on dialects, see {Basic}.
+# 
+# @see https://github.com/jbe/action_tree/wiki The ActionTree Wiki
+
 module ActionTree
 
   require 'action_tree/eval_scope'
   require 'action_tree/capture_hash'
-  require 'action_tree/dialect_helper'
-
-  module Plugins
-    require 'action_tree/plugins/tilt'
-  end
+  require 'action_tree/errors'
+  require 'action_tree/basic'
 
+  include Errors
 
-  module Dialect
-    def new(*prms, &blk)
-      self::Node.new(*prms, &blk)
-    end
-    def apply(mod)
-      self::Node.send(:include, mod::NodeMixin)
-      self::Match.send(:include, mod::MatchMixin)
-      self::Match::DEFAULT_HELPERS << mod::Helpers
-    end
-  end
-
-  # load basic dialect
-  module Basic
-    extend Dialect
-    require "action_tree/basic/node"
-    require "action_tree/basic/match"
-  end
+  # @private
+  # Named procs that can be applied to trees.
+  MACROS = {}
 
-  # shorthand
+  # Create a new {Basic} ActionTree.
+  #
+  # @yield Constructs the tree from the given block of directives
+  #
+  # @example
+  #   a = ActionTree.new do
+  #     action('hi') { "Hello!" }
+  #   end
+  #   a.match('hi').run #=> "Hello!"
+  #
+  # @see Basic::Node
+  #
+  # @return [Basic::Node] Root node of the created tree
   def self.new(&blk)
     Basic.new(&blk)
   end
 
-  # layer proc wrapper
-  class Layer < Proc; end
-  def layer(*prms, &blk)
-    Layer.new(*prms, &blk)
+  # Create an optionally named macro. If a name is given, the macro is remembered by that name, and can later be referenced using {Basic::Node#apply}.
+  #
+  # @return [Proc] The macro
+  def self.macro(name=nil, &blk)
+    name ? (MACROS[name] = blk) : blk
   end
 
 end

data/lib/action_tree/basic.rb

@@ -0,0 +1,36 @@
+
+# The basic ActionTree namespace that other dialects build upon. Contains default config values, default helpers, and the {Node} and {Query} classes that make up ActionTree's main logic.
+#
+# @see https://github.com/jbe/action_tree/wiki/Dialects-and-components Wiki page about dialects and components
+#
+
+module ActionTree::Basic
+
+  CONFIG  = {}
+  require 'action_tree/basic/helpers'
+
+  module ClassMethods
+
+    # Create a new ActionTree (or rather, {Node})
+    # of this dialect
+	def new(*prms, &blk)
+	  self::Node.new(*prms, &blk)
+	end
+
+    # Use a component. The component will be used by all
+    # descending dialects, and must not be used again.
+    def use(component)
+      self::Node.send    :include, component::NodeMethods
+      self::Query.send   :include, component::QueryMethods
+      self::Helpers.send :include, component::Helpers
+      self::CONFIG.merge!          component::CONFIG
+    end
+  end
+
+  extend ClassMethods
+
+  require "action_tree/basic/shared"
+  require "action_tree/basic/node"
+  require "action_tree/basic/query"
+end
+

data/lib/action_tree/basic/helpers.rb

@@ -0,0 +1,20 @@
+
+# Contains the default helpers available inside an ActionTree
+# execution scope.
+#
+# @see https://github.com/jbe/action_tree/wiki/Basic-usage Wiki on basic usage
+
+module ActionTree::Basic::Helpers
+
+  # Writes a configuration value if it
+  # has not been set already
+  def default(key, value)
+    @_conf[key] ||= value
+  end
+
+  # Writes or overwrites a configuration value
+  def set(key, value)
+    @_conf[key] = value
+  end
+
+end

data/lib/action_tree/basic/node.rb

@@ -1,167 +1,358 @@
 
+
+# Every ActionTree fundamentally consists of Nodes. The {Node} class
+# contains the methods used to build trees (the DSL). It is the
+# core of ActionTree.
+#
+# @see https://github.com/jbe/action_tree/wiki The ActionTree Wiki
+
 class ActionTree::Basic::Node
 
-  include ::ActionTree::DialectHelper
+  include ActionTree::Basic::Shared
+  include ActionTree::Errors
+
+  # The token that request path fragments will be matched against.
+  # @return [String, Symbol, Regex]
+  attr_reader :token
+
+  # The nodes children; representing its direct sub-paths.
+  # @return [Set]
+  attr_reader :children
+
+  # The module containing any user defined helpers.
+  # @return [Module]
+  attr_reader :helper_scope
+
+  # The configuration values set for the node.
+  # @return [Hash]
+  attr_reader :config
+
+  # The actions defined for the node. `nil` is used for the default action.
+  # @return [Hash]
+  attr_reader :actions
+
+  # The procs to be invoked before the action is run.
+  # @return [Array]
+  attr_reader :before_hooks
+
+  # The procs to be invoked after the action is run.
+  # @return [Array]
+  attr_reader :after_hooks
+
+  # The procs to chain-process the result of running the action.
+  # @return [Array]
+  attr_reader :processors
+
+  # Same as {Node#processors}, but also processes child nodes.
+  # @return [Array]
+  attr_reader :deep_processors
 
-  attr_reader   :token, :children, :helper_scope,
-                :action_namespaces, :before_hooks,
-                :after_hooks, :postprocessors
-  attr_accessor :not_found_handler
+  # The hash of procs that will handle exceptions in child node actions.
+  # @return [Hash] where `ErrorClass => proc {|err| handler }`
+  attr_accessor :exception_handlers
 
 
-  def initialize(path=[], &blk)
-    path = parse_path(path)
-    @token          = path.shift
-    @children       = Set.new
-    @helper_scope   = Module.new
-    @before_hooks   = []
-    @after_hooks    = []
-    @postprocessors = []
-    @action_namespaces = {}
-    @not_found_handler = nil
-    route(path, &blk) if block_given?
+  # Create a new Node or tree of Nodes.
+  #
+  # @param [nil, String, Symbol, Regexp] token An optional node token. Not needed for root nodes unless the it is later mounted as a child somewhere.
+  #
+  # @yield Takes an optional block to be evaluated inside the Node. This is used to construct the ActionTree, using the "DSL".
+  #
+  def initialize(token=nil, &blk)
+    @token                = token       # string, symbol or regex
+    @children             = Set.new     # set of nodes
+    @helper_scope         = Module.new
+    @config               = {}
+    @actions              = {}          # {:name => proc {...}}
+    @before_hooks         = []          # [procs] without params
+    @after_hooks          = []          # [procs] without params
+    @processors           = []          # [procs] with one param
+    @deep_processors      = []          # ditto
+    @exception_handlers   = {}          # {ErrClass => proc {...}}
+    route([], &blk) if blk
   end
 
-  # INSPECTION
 
+  ##  INSPECTION
+
+  # String representation for inspecting the node.
+  # @return [String]
   def inspect
     "#<#{self.class}:#{self.object_id.to_s(16)} #{@token.inspect} >"
   end
 
+  # A tree-like multiline string of descending nodes.
+  # @return [String]
   def printout(stack='')
     stack + @token.inspect + "\n" +
     @children.map {|c| c.printout(stack + '  ') }.join
   end
 
-  # MATCHING
-  
-  def regexp
-    @regexp ||=
-      Regexp.new('^' + case @token
-        when Regexp then "(#{@token.source})"
-        when Symbol then '(.+)'
-        when String then @token.gsub(/:\w+/, '(.+)')
-        #when nil    then '\/*'
-      end + '$')
-  end
 
-  def match?(path_fragment)
-    !!path_fragment.match(regexp)
-  end
+  ##  DSL
 
-  def capture_names
-    case @token
-      when Regexp then ['match']
-      when Symbol then [@token.to_s]
-      when String
-        @token.scan(/:\w+/).map {|m| m[1..-1] }
+  # Find or create a descending node.
+  #
+  # @param [Array, String, Symbol, Regexp, nil] location
+  #   A Node location relative to this Node
+  # 
+  # @see https://github.com/jbe/action_tree/wiki/Definitions Location format specification in the Wiki
+  #
+  # @return [Node] at the given relative location.
+  #   Created automatically if it does not exist.
+  def locate(location)
+    loc = parse_path(location)
+    if loc.empty? then self else
+      token = loc.shift
+      (get_child(token) || make_child(token)).locate(loc)
     end
   end
-
-
-  # DSL
-
+  
+  # Evaluate the given block in a descending node,
+  # at the specified `location`.
+  #
+  # @param location (see #locate)
+  # @yield Takes a block to be evaluated at `location`
+  #
+  # @return [Node] self
   def route(location=nil, &blk)
-    descend(location).instance_eval(&blk) if blk
+    if blk.nil? && location.is_a?(Proc)
+      blk      = location
+      location = nil
+    end
+    locate(location).instance_eval(&blk)
     self
   end
-  alias :with :route
-  alias :w :route
-  alias :r :route
-  alias :_ :route
-  def apply(layer); route(&layer); end
+  alias :with   :route
+  alias :w      :route
+  alias :r      :route
+
+  # Apply a (named) `Proc`, referred to as a macro.
+  #
+  # @param [Proc, Object] macro
+  #   A Proc or the name of a stored proc (defined using
+  #   {ActionTree.macro}) to be evaluated in the node.
+  #
+  def apply(macro)
+    case macro
+      when Proc then route(&macro)
+      else route(&::ActionTree::MACROS[macro])
+    end
+  end
 
-  def action(location=nil, namespace=:default, &blk)
-    descend(location).action_namespaces[namespace] = blk
+  # Define an optionally namespaced action, optionally at
+  # the specified `location`.
+  #
+  # @param location (see #locate)
+  # @param namespace The name of the action. Used to
+  #   place actions within a namespace (e.g. for HTTP verbs).
+  #
+  # @yield Takes a block containing the action.
+  #
+  # @return [Node] self
+  def action(location=nil, namespace=nil, &blk)
+    locate(location).actions[namespace] = blk
     self
   end
   alias :a :action
-  alias :o :action
-  def get(   loc=nil, &blk); action(loc, :get,    &blk);  end
-  def put(   loc=nil, &blk); action(loc, :put,    &blk);  end
-  def post(  loc=nil, &blk); action(loc, :post,   &blk);  end
-  def delete(loc=nil, &blk); action(loc, :delete, &blk);  end
 
+  # Define helper methods
+  # Open a scope for defining helper methods, optionally at the specified `location`. They will be available to this node, as well as all descendants.
+  #
+  # @param location (see #locate)
+  #
+  # @yield Takes a block containing helper method definitions.
+  #
+  # @example
+  #   a = ActionTree.new do
+  #     helpers do
+  #       def sing
+  #         'lala'
+  #       end
+  #     end
+  #
+  #     action { sing }
+  #   end
+  #
+  #   a.match('/').run # => "lala"
+  #
   def helpers(location=nil, &blk)
-    descend(location).helper_scope.module_eval(&blk)
+    locate(location).helper_scope.module_eval(&blk)
   end
 
+  # Add a before hook, optionally at the specified `location`. It will apply to this node, as well as all descendants.
+  #
+  # @param location (see #locate)
+  #
+  # @yield Takes a block containing the hook to be run.
   def before(location=nil, &blk)
-    descend(location).before_hooks << blk if blk
+    locate(location).before_hooks << blk
   end
   alias :b :before
 
+  # Add an after hook, optionally at the specified `location`. Like the {Node#before} hook, it will also apply to all descendants.
+  #
+  # @param location (see #locate)
+  #
+  # @yield (see #before)
   def after(location=nil, &blk)
-    descend(location).after_hooks << blk if blk
+    locate(location).after_hooks << blk
+  end
+  alias :af :after
+
+  # Add an exception handler
+  #
+  # @example
+  #   handle(MyException) do |err|
+  #     "oops, #{err}"
+  #   end
+  def handle(error_class, &blk)
+    unless error_class.ancestors.include?(Exception)
+      raise ArgumentError, "#{error_class.inspect} is not an exception."
+    end
+    @exception_handlers[error_class] = blk
+  end
+  alias :h :handle
+
+  # Add a processor
+  def processor(location=nil, &blk)
+    locate(location).processors << blk
   end
+  alias :p :processor
 
-  def not_found(location=nil, &blk)
-    descend(location).not_found_handler = blk if blk
+  # Add a deep processor
+  def deep_processor(location=nil, &blk)
+    locate(location).deep_processors << blk
   end
-  alias :x :not_found
+  alias :dp :deep_processor
 
-  def postprocessor(location=nil, &blk)
-    descend(location).postprocessors << blk if blk
+  # Set a configuration value
+  def set(key, value)
+    config[key] = value
   end
-  alias :p :postprocessor
 
+  # Add the children of another Node to the children
+  # of this Node.
   def mount(node, location=nil)
-      if node.token
-        descend(location).children < node
-      else
-        raise 'root nodes can not be mounted. apply a layer instead.'
-      end
+    locate(location).add_child(*node.children)
+  end
+
+  # Add one or several children to the node, provided
+  # they are compatible (i.e. of the same dialect).
+  def add_child(*nodes)
+    nodes.each {|n| validate_child(n) }
+    children << nodes
   end
 
-  
-  # LOOKUPS
 
-  def match(path=[])
-    dialect::Match.new(self, nil, nil).match(path)
+  ##  MATCHING METHODS
+
+  # Match a against a request path, building a chain of {Query} objects.
+  #
+  # @param [String, Array] path The lookup path to query.
+  # @param namespace The action namespace.
+  #
+  # @return [Query] the result (even when not found).
+  def match(path=[], namespace=nil)
+    dialect::Query.new(self, nil, nil, namespace).match(path)
   end
+  alias :query :match
 
-  def descend(path)
-    loc = parse_path(path)
-    if loc.empty? then self else
-      token = loc.shift
-      (get_child(token) || make_child(token)).descend(loc)
+
+
+  # === End of public API ===
+
+
+  # Check if a path fragment matches the node token.
+  # @private
+  def match?(path_fragment)
+    path_fragment.match(regexp)
+  end
+
+  # The names that this node will capture to.
+  # @private
+  def capture_names
+    @capture_names ||= case @token
+      when Regexp then ['match']
+      when Symbol then [@token.to_s]
+      when String
+        @token.scan(/:\w+/).map {|m| m[1..-1] }
     end
   end
 
+  # Reads captures from a path fragment, storing them
+  # under their names in a {CaptureHash}
+  # @private
+  def read_captures(fragment, hsh)
+    return hsh if capture_names.empty?
+    captures = fragment.match(regexp).captures
+    capture_names.each_with_index do |name, i|
+      hsh.add(name, captures[i])
+    end; hsh
+  end
 
   private
 
-    def get_child(token)
-      @children.each do |child|
-        return child if child.token == token
-      end; nil
-    end
+  # regexp to see if a path fragment matches
+  # this node's token
+  def regexp
+    @regexp ||=
+      Regexp.new('^' + case @token
+        when Regexp then "(#{@token.source})"
+        when Symbol then '(.+)'
+        when String then @token.gsub(/:\w+/, '(.+)')
+      end + '$')
+  end
 
-    def make_child(token)
-      child = self.class.new(token)
-      @children << child
-      child
+  def get_child(token)
+    @children.each do |child|
+      return child if child.token == token
+    end; nil
+  end
+
+  def make_child(token)
+    child = self.class.new(token)
+    @children << child
+    child
+  end
+
+  # convert any valid path syntax to array syntax
+  def parse_path(path)
+    case path
+      when nil            then []
+      when Array          then path
+      when Regexp, Symbol then [path]
+      when String         then parse_string_path(path)
+      else
+        raise "invalid path #{path}"
     end
+  end
 
-    # convert any valid path syntax to array syntax
-    def parse_path(path)
-      case path
-        when nil            then []
-        when Array          then path
-        when Regexp, Symbol then [path]
-        when String         then parse_string_path(path)
-        else
-          raise "invalid path #{path}"
+  # convert a string to array path syntax
+  def parse_string_path(path)
+    path.gsub(/(^\/)|(\/$)/, ''). # remove trailing slashes
+      split('/').map do |str|     # split tokens
+        str.match(/^:\w+$/) ?     # replace ':c' with :c
+          str[1..-1].to_sym : str
       end
-    end
+  end
 
-    # convert a string to array path syntax
-    def parse_string_path(path)
-      path.gsub(/(^\/)|(\/$)/, ''). # remove trailing slashes
-        split('/').map do |str|     # split tokens
-          str.match(/^:\w+$/) ?     # replace ':c' with :c
-            str[1..-1].to_sym : str
-        end
+  # raises errors if the provided node for some
+  # reason cannot be added as a child to this node.
+  def validate_child(node)
+    case
+    when !self.compatible_with(node)
+      raise "cannot add child with class " +
+      "#{node.class} to #{self.inspect}"
+    when children.map(&:token).include?(node.token)
+      raise 'cannot add child with occupied token: ' +
+      node.token.inspect
+    else true
     end
+  end
+
+  def compatible_with?(node)
+    node.class == self.class
+  end
 end