Class: StateMachines::State
- Inherits:
-
Object
- Object
- StateMachines::State
- Defined in:
- lib/state_machines/state.rb
Overview
A state defines a value that an attribute can be in after being transitioned 0 or more times. States can represent a value of any type in Ruby, though the most common (and default) type is String.
In addition to defining the machine’s value, a state can also define a behavioral context for an object when that object is in the state. See StateMachines::Machine#state for more information about how state-driven behavior can be utilized.
Instance Attribute Summary collapse
-
#cache ⇒ Object
Whether this state’s value should be cached after being evaluated.
-
#human_name(klass = @machine.owner_class) ⇒ Object
Transforms the state name into a more human-readable format, such as “first gear” instead of “first_gear”.
-
#initial ⇒ Object
(also: #initial?)
Whether or not this state is the initial state to use for new objects.
-
#machine ⇒ Object
The state machine for which this state is defined.
-
#matcher ⇒ Object
A custom lambda block for determining whether a given value matches this state.
-
#name ⇒ Object
readonly
The unique identifier for the state used in event and callback definitions.
-
#qualified_name ⇒ Object
readonly
The fully-qualified identifier for the state, scoped by the machine’s namespace.
-
#value(eval = true) ⇒ Object
The value that represents this state.
Instance Method Summary collapse
-
#call(object, method, *args, &block) ⇒ Object
Calls a method defined in this state’s context on the given object.
-
#context(&block) ⇒ Object
Defines a context for the state which will be enabled on instances of the owner class when the machine is in this state.
-
#context_methods ⇒ Object
The list of methods that have been defined in this state’s context.
-
#description(options = {}) ⇒ Object
Generates a human-readable description of this state’s name / value:.
- #draw(graph, options = {}) ⇒ Object
-
#final? ⇒ Boolean
Determines whether there are any states that can be transitioned to from this state.
-
#initialize(machine, name, options = {}) ⇒ State
constructor
Creates a new state within the context of the given machine.
-
#initialize_copy(orig) ⇒ Object
Creates a copy of this state, excluding the context to prevent conflicts across different machines.
-
#inspect ⇒ Object
Generates a nicely formatted description of this state’s contents.
-
#matches?(other_value) ⇒ Boolean
Determines whether this state matches the given value.
Constructor Details
#initialize(machine, name, options = {}) ⇒ State
Creates a new state within the context of the given machine.
Configuration options:
-
:initial
- Whether this state is the beginning state for the machine. Default is false. -
:value
- The value to store when an object transitions to this state. Default is the name (stringified). -
:cache
- If a dynamic value (via a lambda block) is being used, then setting this to true will cache the evaluated result -
:if
- Determines whether a value matches this state (e.g. :value => lambda Time.now, :if => lambda {|state| !state.nil?}). By default, the configured value is matched. -
:human_name
- The human-readable version of this state’s name
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 |
# File 'lib/state_machines/state.rb', line 53 def initialize(machine, name, = {}) #:nodoc: .assert_valid_keys(:initial, :value, :cache, :if, :human_name) @machine = machine @name = name @qualified_name = name && machine.namespace ? :"#{machine.namespace}_#{name}" : name @human_name = [:human_name] || (@name ? @name.to_s.tr('_', ' ') : 'nil') @value = .include?(:value) ? [:value] : name && name.to_s @cache = [:cache] @matcher = [:if] @initial = [:initial] == true @context = StateContext.new(self) if name conflicting_machines = machine.owner_class.state_machines.select { |other_name, other_machine| other_machine != machine && other_machine.states[qualified_name, :qualified_name] } # Output a warning if another machine has a conflicting qualified name # for a different attribute if conflict = conflicting_machines.detect { |other_name, other_machine| other_machine.attribute != machine.attribute } name, other_machine = conflict warn "State #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}" elsif conflicting_machines.empty? # Only bother adding predicates when another machine for the same # attribute hasn't already done so add_predicate end end end |
Instance Attribute Details
#cache ⇒ Object
Whether this state’s value should be cached after being evaluated
30 31 32 |
# File 'lib/state_machines/state.rb', line 30 def cache @cache end |
#human_name(klass = @machine.owner_class) ⇒ Object
Transforms the state name into a more human-readable format, such as “first gear” instead of “first_gear”
105 106 107 |
# File 'lib/state_machines/state.rb', line 105 def human_name(klass = @machine.owner_class) @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name end |
#initial ⇒ Object Also known as: initial?
Whether or not this state is the initial state to use for new objects
33 34 35 |
# File 'lib/state_machines/state.rb', line 33 def initial @initial end |
#machine ⇒ Object
The state machine for which this state is defined
13 14 15 |
# File 'lib/state_machines/state.rb', line 13 def machine @machine end |
#matcher ⇒ Object
A custom lambda block for determining whether a given value matches this state
38 39 40 |
# File 'lib/state_machines/state.rb', line 38 def matcher @matcher end |
#name ⇒ Object (readonly)
The unique identifier for the state used in event and callback definitions
16 17 18 |
# File 'lib/state_machines/state.rb', line 16 def name @name end |
#qualified_name ⇒ Object (readonly)
The fully-qualified identifier for the state, scoped by the machine’s namespace
20 21 22 |
# File 'lib/state_machines/state.rb', line 20 def qualified_name @qualified_name end |
#value(eval = true) ⇒ Object
The value that represents this state. This will optionally evaluate the original block if it’s a lambda block. Otherwise, the static value is returned.
For example,
State.new(machine, :parked, :value => 1).value # => 1
State.new(machine, :parked, :value => lambda {Time.now}).value # => Tue Jan 01 00:00:00 UTC 2008
State.new(machine, :parked, :value => lambda {Time.now}).value(false) # => <Proc:0xb6ea7ca0@...>
138 139 140 141 142 143 144 145 146 147 148 149 150 |
# File 'lib/state_machines/state.rb', line 138 def value(eval = true) if @value.is_a?(Proc) && eval if cache_value? @value = @value.call machine.states.update(self) @value else @value.call end else @value end end |
Instance Method Details
#call(object, method, *args, &block) ⇒ Object
Calls a method defined in this state’s context on the given object. All arguments and any block will be passed into the method defined.
If the method has never been defined for this state, then a NoMethodError will be raised.
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 |
# File 'lib/state_machines/state.rb', line 214 def call(object, method, *args, &block) = args.last.is_a?(Hash) ? args.pop : {} = {:method_name => method}.merge() state = machine.states.match!(object) if state == self && object.respond_to?(method) object.send(method, *args, &block) elsif method_missing = [:method_missing] # Dispatch to the superclass since the object either isn't in this state # or this state doesn't handle the method begin method_missing.call rescue NoMethodError => ex if ex.name.to_s == [:method_name].to_s && ex.args == args # No valid context for this method raise InvalidContext.new(object, "State #{state.name.inspect} for #{machine.name.inspect} is not a valid context for calling ##{[:method_name]}") else raise end end end end |
#context(&block) ⇒ Object
Defines a context for the state which will be enabled on instances of the owner class when the machine is in this state.
This can be called multiple times. Each time a new context is created, a new module will be included in the owner class.
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 |
# File 'lib/state_machines/state.rb', line 176 def context(&block) # Include the context context = @context machine.owner_class.class_eval { include context } # Evaluate the method definitions and track which ones were added old_methods = context_methods context.class_eval(&block) new_methods = context_methods.to_a.select { |(name, method)| old_methods[name] != method } # Alias new methods so that the only execute when the object is in this state new_methods.each do |(method_name, method)| context_name = context_name_for(method_name) context.class_eval <<-end_eval, __FILE__, __LINE__ + 1 alias_method :"#{context_name}", :#{method_name} def #{method_name}(*args, &block) state = self.class.state_machine(#{machine.name.inspect}).states.fetch(#{name.inspect}) options = {:method_missing => lambda {super(*args, &block)}, :method_name => #{method_name.inspect}} state.call(self, :"#{context_name}", *(args + [options]), &block) end end_eval end true end |
#context_methods ⇒ Object
The list of methods that have been defined in this state’s context
203 204 205 206 207 |
# File 'lib/state_machines/state.rb', line 203 def context_methods @context.instance_methods.inject({}) do |methods, name| methods.merge(name.to_sym => @context.instance_method(name)) end end |
#description(options = {}) ⇒ Object
Generates a human-readable description of this state’s name / value:
For example,
State.new(machine, :parked).description # => "parked"
State.new(machine, :parked, :value => :parked).description # => "parked"
State.new(machine, :parked, :value => nil).description # => "parked (nil)"
State.new(machine, :parked, :value => 1).description # => "parked (1)"
State.new(machine, :parked, :value => lambda {Time.now}).description # => "parked (*)
Configuration options:
-
:human_name
- Whether to use this state’s human name in the description or just the internal name
122 123 124 125 126 127 |
# File 'lib/state_machines/state.rb', line 122 def description( = {}) label = [:human_name] ? human_name : name description = label ? label.to_s : label.inspect description << " (#{@value.is_a?(Proc) ? '*' : @value.inspect})" unless name.to_s == @value.to_s description end |
#draw(graph, options = {}) ⇒ Object
237 238 239 |
# File 'lib/state_machines/state.rb', line 237 def draw(graph, = {}) fail NotImplementedError end |
#final? ⇒ Boolean
Determines whether there are any states that can be transitioned to from this state. If there are none, then this state is considered final. Any objects in a final state will remain so forever given the current machine’s definition.
93 94 95 96 97 98 99 100 101 |
# File 'lib/state_machines/state.rb', line 93 def final? !machine.events.any? do |event| event.branches.any? do |branch| branch.state_requirements.any? do |requirement| requirement[:from].matches?(name) && !requirement[:to].matches?(name, :from => name) end end end end |
#initialize_copy(orig) ⇒ Object
Creates a copy of this state, excluding the context to prevent conflicts across different machines.
84 85 86 87 |
# File 'lib/state_machines/state.rb', line 84 def initialize_copy(orig) #:nodoc: super @context = StateContext.new(self) end |
#inspect ⇒ Object
Generates a nicely formatted description of this state’s contents.
For example,
state = StateMachines::State.new(machine, :parked, :value => 1, :initial => true)
state # => #<StateMachines::State name=:parked value=1 initial=true context=[]>
247 248 249 250 |
# File 'lib/state_machines/state.rb', line 247 def inspect attributes = [[:name, name], [:value, @value], [:initial, initial?]] "#<#{self.class} #{attributes.map { |attr, value| "#{attr}=#{value.inspect}" } * ' '}>" end |
#matches?(other_value) ⇒ Boolean
Determines whether this state matches the given value. If no matcher is configured, then this will check whether the values are equivalent. Otherwise, the matcher will determine the result.
For example,
# Without a matcher
state = State.new(machine, :parked, :value => 1)
state.matches?(1) # => true
state.matches?(2) # => false
# With a matcher
state = State.new(machine, :parked, :value => lambda {Time.now}, :if => lambda {|value| !value.nil?})
state.matches?(nil) # => false
state.matches?(Time.now) # => true
167 168 169 |
# File 'lib/state_machines/state.rb', line 167 def matches?(other_value) matcher ? matcher.call(other_value) : other_value == value end |