Hooks and history
Hooks fire after the main steps, when the outcome is already known. Measurement keeps a record of what ran and for how long. You declare both on the class, and a subclass gets a copy at the moment it is created.
on_success(target, **options)on_failure(target, **options)on_skip(target, **options)always(target, **options)A hook accepts what a step accepts: a method name or an action class, plus the step options (if:, unless:, desc: and the rest). Any other key raises DefinitionError at the declaration. Declaring the same hook again swaps it in place. The four lists are readable through Action.success_hooks, failure_hooks, skip_hooks and always_hooks.
The order of a run. It starts only once the input is valid: invalid input returns :invalid_input before step 1, so no step and no hook runs, always included.
- The main steps run in order, all inside a single halt catch.
- The result is whatever was recorded, or a new
Successwhen nothing was. A barehalt!with nothing recorded raises here instead (see Control flow). - Output is refreshed (see Input and output).
- One category is chosen from the result as it stands now: success picks
on_success, skipped pickson_skip, everything else pickson_failure. That choice is final, even when a hook later changes the outcome. - The category’s hooks run in the order declared, then the
alwayshooks run inside a halt catch of their own. - After every hook, a result it recorded is adopted and output is refreshed once more.
BELL = []
class CastOff < Actionable::Action step :inspect_lines step :log_departure, if: :logged? on_failure :ring_bell always :stow_fenders
private
def logged? = true def inspect_lines = fail!(:fogbound) def log_departure = BELL << :log def ring_bell = BELL << :bell def stow_fenders = BELL << :fendersend
CastOff.run.code # => :fogboundBELL # => [:bell, :fenders]CastOff.failure_hooks.map(&:name) # => [:ring_bell]CastOff.always_hooks.map(&:name) # => [:stow_fenders]CastOff.success_hooks.size # => 0CastOff.skip_hooks.size # => 0What a hook may do
Section titled “What a hook may do”Verbs work inside hooks. A plain verb replaces the result and lets the remaining hooks run. A bang verb adopts its result and cuts off the rest of its own category, though always still runs and sees the new result. halt! leaves the result alone and ends the phase. That is why succeed! in an on_failure hook rescues the run, and fail!(:overdue) in an on_success hook turns a success into a failure.
class Reroute < Actionable::Action step :depart on_failure :use_tender
private
def depart = fail!(:ebbing) def use_tender = succeed!('crossed by tender')end
Reroute.run.success? # => trueReroute.run.message # => "crossed by tender"
class PastCurfew < Actionable::Action step :depart on_success :refuse on_success :unreachable
private
def depart = succeed def refuse = fail!(:overdue) def unreachable = raise('not reached')end
PastCurfew.run.code # => :overdueIf a hook raises, the exception travels up at once and nothing after it runs, always hooks too. A hook whose guard says no is passed over. When a hook sets an instance variable named like an output field, the next refresh picks it up.
measure
Section titled “measure”measure(mode = nil, rate: nil)| Mode | Records |
|---|---|
:none (default) |
nothing, so history is [] |
:all |
every run |
:sampled |
that share of runs; needs rate: from 0 to 1 inclusive |
A mode it doesn’t know raises ArgumentError (unknown measure mode), and so does :sampled with a missing or out-of-range rate (measure :sampled requires rate: between 0 and 1). A rate of 1 always records, a rate of 0 never does. Called with no argument, measure returns the mode. The readers behind it are measure_rate, measure_all?, measure_sampled? and measure_sample_hit?. A subclass inherits a snapshot of mode and rate.
Measuring spreads downward: every run nested in a measuring run (action steps, hook actions, run_each items) measures as well, whatever its own measure says. A parent that doesn’t measure passes nothing down. The state lives per fiber, so concurrent runs stay apart, and a run in a different Fiber never shows up in the parent’s history.
class Crossing < Actionable::Action measure :all
step :load_deck on_success :raise_ramp
private
def load_deck = nil def raise_ramp = nilend
Crossing.measure # => :allCrossing.measure_all? # => trueCrossing.measure_rate # => nilCrossing.measure_sampled? # => false
class SpotCheck < Actionable::Action measure :sampled, rate: 0.5end
SpotCheck.measure_rate # => 0.5History
Section titled “History”The history of a measuring run is an Actionable::History, holding one History::Step for each step or hook that ran, in the order they ran. A step blocked by its guard leaves no entry. Each entry is added when its step ends, whether it halted or raised.
| Step field | Meaning |
|---|---|
section |
:main for steps; :success, :failure, :skip for outcome hooks; :always |
name |
the step name, or the child action class for an action step |
started_at |
wall-clock Time |
duration |
monotonic seconds, a Float |
code |
the code of the result the step recorded, or nil when it only set variables |
nested |
the child’s History for an action step in a measuring run, else nil |
A history responds to steps, <<(step) (returns the history), empty?, took (total of the durations), as_json (an Array of step hashes) and to_json (via Oj, compat mode). The as_json keys are section, name, started_at (ISO 8601, six fractional digits), duration, code and history (the nested as_json, or nil); for an action step name is the class name as a String. The entry for an action step times the child run from start to finish.
history = Crossing.run.historyhistory.steps.map { |s| [s.section, s.name] } # => [[:main, :load_deck], [:success, :raise_ramp]]history.empty? # => falsehistory.took.class # => Floathistory.as_json.first.keys # => [:section, :name, :started_at, :duration, :code, :history]history.to_json.class # => StringActionable::Action.run.history # => []See also
Section titled “See also”- Actions and steps: the steps that hooks mirror
- Control flow: the verbs hooks may call
- Batches and introspection:
describelists hooks and measure mode
FieldStruct, Actionable and their adapters are open source under the MIT license.