Class: ActionTree::Basic::Node

Inherits:
Object
  • Object
show all
Includes:
Shared, Errors
Defined in:
lib/action_tree/basic/node.rb

Overview

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 Also:

Direct Known Subclasses

Templated::Node

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Shared

#dialect

Constructor Details

#initialize(token = nil) { ... } ⇒ Node

Create a new Node or tree of Nodes.

Parameters:

  • token (nil, String, Symbol, Regexp) (defaults to: nil) —

    An optional node token. Not needed for root nodes unless the it is later mounted as a child somewhere.

Yields:

  • Takes an optional block to be evaluated inside the Node. This is used to construct the ActionTree, using the "DSL".



61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/action_tree/basic/node.rb', line 61

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

Instance Attribute Details

#actions ⇒ Hash (readonly)

The actions defined for the node. nil is used for the default action.

Returns:

  • (Hash) 


32
33
34
 
# File 'lib/action_tree/basic/node.rb', line 32

def actions
  @actions
end

#after_hooks ⇒ Array (readonly)

The procs to be invoked after the action is run.

Returns:

  • (Array) 


40
41
42
 
# File 'lib/action_tree/basic/node.rb', line 40

def after_hooks
  @after_hooks
end

#before_hooks ⇒ Array (readonly)

The procs to be invoked before the action is run.

Returns:

  • (Array) 


36
37
38
 
# File 'lib/action_tree/basic/node.rb', line 36

def before_hooks
  @before_hooks
end

#children ⇒ Set (readonly)

The nodes children; representing its direct sub-paths.

Returns:

  • (Set) 


20
21
22
 
# File 'lib/action_tree/basic/node.rb', line 20

def children
  @children
end

#config ⇒ Hash (readonly)

The configuration values set for the node.

Returns:

  • (Hash) 


28
29
30
 
# File 'lib/action_tree/basic/node.rb', line 28

def config
  @config
end

#deep_processors ⇒ Array (readonly)

Same as #processors, but also processes child nodes.

Returns:

  • (Array) 


48
49
50
 
# File 'lib/action_tree/basic/node.rb', line 48

def deep_processors
  @deep_processors
end

#exception_handlers ⇒ Hash

The hash of procs that will handle exceptions in child node actions.

Returns:

  • (Hash) —

    where ErrorClass => proc {|err| handler }



52
53
54
 
# File 'lib/action_tree/basic/node.rb', line 52

def exception_handlers
  @exception_handlers
end

#helper_scope ⇒ Module (readonly)

The module containing any user defined helpers.

Returns:

  • (Module) 


24
25
26
 
# File 'lib/action_tree/basic/node.rb', line 24

def helper_scope
  @helper_scope
end

#processors ⇒ Array (readonly)

The procs to chain-process the result of running the action.

Returns:

  • (Array) 


44
45
46
 
# File 'lib/action_tree/basic/node.rb', line 44

def processors
  @processors
end

#token ⇒ String, ... (readonly)

The token that request path fragments will be matched against.

Returns:

  • (String, Symbol, Regex) 


16
17
18
 
# File 'lib/action_tree/basic/node.rb', line 16

def token
  @token
end

Instance Method Details

#action(location = nil, namespace = nil) { ... } ⇒ Node Also known as: a

Define an optionally namespaced action, optionally at the specified location.

Parameters:

  • namespace (defaults to: nil) —

    The name of the action. Used to place actions within a namespace (e.g. for HTTP verbs).

  • location (Array, String, Symbol, Regexp, nil) (defaults to: nil) —

    A Node location relative to this Node

Yields:

  • Takes a block containing the action.

Returns:



153
154
155
156
 
# File 'lib/action_tree/basic/node.rb', line 153

def action(location=nil, namespace=nil, &blk)
  locate(location).actions[namespace] = blk
  self
end

#add_child(*nodes) ⇒ Object

Add one or several children to the node, provided they are compatible (i.e. of the same dialect).



242
243
244
245
 
# File 'lib/action_tree/basic/node.rb', line 242

def add_child(*nodes)
  nodes.each {|n| validate_child(n) }
  children << nodes
end

#after(location = nil) { ... } ⇒ Object Also known as: af

Add an after hook, optionally at the specified location. Like the #before hook, it will also apply to all descendants.

Parameters:

  • location (Array, String, Symbol, Regexp, nil) (defaults to: nil) —

    A Node location relative to this Node

Yields:

  • Takes a block containing the hook to be run.



198
199
200
 
# File 'lib/action_tree/basic/node.rb', line 198

def after(location=nil, &blk)
  locate(location).after_hooks << blk
end

#apply(macro) ⇒ Object

Apply a (named) Proc, referred to as a macro.

Parameters:

  • macro (Proc, Object) —

    A Proc or the name of a stored proc (defined using ActionTree.macro) to be evaluated in the node.



136
137
138
139
140
141
 
# File 'lib/action_tree/basic/node.rb', line 136

def apply(macro)
  case macro
    when Proc then route(&macro)
    else route(&::ActionTree::MACROS[macro])
  end
end

#before(location = nil) { ... } ⇒ Object Also known as: b

Add a before hook, optionally at the specified location. It will apply to this node, as well as all descendants.

Parameters:

  • location (Array, String, Symbol, Regexp, nil) (defaults to: nil) —

    A Node location relative to this Node

Yields:

  • Takes a block containing the hook to be run.



188
189
190
 
# File 'lib/action_tree/basic/node.rb', line 188

def before(location=nil, &blk)
  locate(location).before_hooks << blk
end

#deep_processor(location = nil, &blk) ⇒ Object Also known as: dp

Add a deep processor



224
225
226
 
# File 'lib/action_tree/basic/node.rb', line 224

def deep_processor(location=nil, &blk)
  locate(location).deep_processors << blk
end

#handle(error_class, &blk) ⇒ Object Also known as: h

Add an exception handler

Examples:

handle(MyException) do |err|
  "oops, #{err}"
end


209
210
211
212
213
214
 
# File 'lib/action_tree/basic/node.rb', line 209

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

#helpers(location = nil) { ... } ⇒ Object

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.

Examples:

a = ActionTree.new do
  helpers do
    def sing
      'lala'
    end
  end

  action { sing }
end

a.match('/').run # => "lala"

Parameters:

  • location (Array, String, Symbol, Regexp, nil) (defaults to: nil) —

    A Node location relative to this Node

Yields:

  • Takes a block containing helper method definitions.



179
180
181
 
# File 'lib/action_tree/basic/node.rb', line 179

def helpers(location=nil, &blk)
  locate(location).helper_scope.module_eval(&blk)
end

#inspect ⇒ String

String representation for inspecting the node.

Returns:

  • (String) 


80
81
82
 
# File 'lib/action_tree/basic/node.rb', line 80

def inspect
  "#<#{self.class}:#{self.object_id.to_s(16)} #{@token.inspect} >"
end

#locate(location) ⇒ Node

Find or create a descending node.

Parameters:

  • location (Array, String, Symbol, Regexp, nil) —

    A Node location relative to this Node

Returns:

  • (Node) —

    at the given relative location. Created automatically if it does not exist.

See Also:



103
104
105
106
107
108
109
 
# File 'lib/action_tree/basic/node.rb', line 103

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

#match(path = [], namespace = nil) ⇒ Query Also known as: query

Match a against a request path, building a chain of Query objects.

Parameters:

  • path (String, Array) (defaults to: []) —

    The lookup path to query.

  • namespace (defaults to: nil) —

    The action namespace.

Returns:

  • (Query) —

    the result (even when not found).



256
257
258
 
# File 'lib/action_tree/basic/node.rb', line 256

def match(path=[], namespace=nil)
  dialect::Query.new(self, nil, nil, namespace).match(path)
end

#mount(node, location = nil) ⇒ Object

Add the children of another Node to the children of this Node.



236
237
238
 
# File 'lib/action_tree/basic/node.rb', line 236

def mount(node, location=nil)
  locate(location).add_child(*node.children)
end

#printout(stack = '') ⇒ String

A tree-like multiline string of descending nodes.

Returns:

  • (String) 


86
87
88
89
 
# File 'lib/action_tree/basic/node.rb', line 86

def printout(stack='')
  stack + @token.inspect + "\n" +
  @children.map {|c| c.printout(stack + '  ') }.join
end

#processor(location = nil, &blk) ⇒ Object Also known as: p

Add a processor



218
219
220
 
# File 'lib/action_tree/basic/node.rb', line 218

def processor(location=nil, &blk)
  locate(location).processors << blk
end

#route(location = nil) { ... } ⇒ Node Also known as: with, w, r

Evaluate the given block in a descending node, at the specified location.

Parameters:

  • location (Array, String, Symbol, Regexp, nil) (defaults to: nil) —

    A Node location relative to this Node

Yields:

  • Takes a block to be evaluated at location

Returns:



118
119
120
121
122
123
124
125
 
# File 'lib/action_tree/basic/node.rb', line 118

def route(location=nil, &blk)
  if blk.nil? && location.is_a?(Proc)
    blk      = location
    location = nil
  end
  locate(location).instance_eval(&blk)
  self
end

#set(key, value) ⇒ Object

Set a configuration value



230
231
232
 
# File 'lib/action_tree/basic/node.rb', line 230

def set(key, value)
  config[key] = value
end