Skip to content

Actions and steps

An action subclasses Actionable::Action, and each of its steps is an instance method (public or private). Every .run creates a new instance, so nothing carries over between calls. Here we cover how to declare steps and how to run them. The verbs that end a run live on Control flow, and the object .run hands back is on Results.

Action.run(*args, **kwargs) # => Result

When the class has an input block, .run(**kwargs) builds the input struct and the steps read it as input (see Input and output). Without the block the action is free-form, so .run forwards *args and **kwargs to new and the default constructor discards them. You always get exactly one result back, and a run that records no outcome succeeds on its own.

class StampPass < Actionable::Action
input { required :pass_no, :string }
output { required :stamped_no, :string }
step :stamp
private
def stamp
@stamped_no = input.pass_no.delete('/')
end
end
StampPass.run(pass_no: 'BP/204/7').stamped_no # => "BP2047"
StampPass.steps.map(&:name) # => [:stamp]
StampPass.run.code # => :invalid_input

A free-form action that wants its own arguments overrides initialize and calls super():

class Hail < Actionable::Action
def initialize(vessel)
super()
@vessel = vessel
end
step :hail
private
def hail = succeed("ahoy #{@vessel}")
end
Hail.run('Gannet').message # => "ahoy Gannet"
Actionable::Action.run.success? # => true
step(target, **options)
Target Kind Meaning
Symbol or String :method call the instance method of that name
an Action subclass :action run that action as a step (see nested actions)
Option Applies to Meaning
if: all steps run only when the guard is truthy
unless: all steps skip when the guard is truthy
input: action steps names of instance variables to pass to the child
expose: action steps narrow the child’s output fields copied back
desc: all steps and hooks a description for people, a String (see Descriptions)

Any other key raises DefinitionError when the step is declared, with a suggestion when one is close (unknown step option iff: on Kiln#fire (did you mean if:?)), so a typo can’t quietly turn a guard off. The same check covers hooks, case_step and its branches.

An adapter that reads its own key from step.options registers it with Actionable.register_step_option(name, owner:) when it’s required. owner: names the gem or app that reads it and shows up in messages. Registering the same key twice with the same owner does nothing; another owner, or a built-in key, raises ArgumentError. Actionable.registered_step_options lists what’s registered.

Actionable.register_step_option(:kiln_temp, owner: 'glass-kiln') # => :kiln_temp
Actionable.registered_step_options[:kiln_temp] # => "glass-kiln"
class Fire < Actionable::Action
step :heat, kiln_temp: 540
private
def heat = nil
end
Fire.steps.first.options # => {kiln_temp: 540}

Steps execute in the order declared, and step 'name' is the same step as step :name. Any other kind of target (step 5) raises ArgumentError with unsupported step target. A step object answers name, kind and options, and two steps are equal when their class and name match. Action.steps lists them in order.

if: and unless: accept a method name or a callable that gets the instance; anything else raises ArgumentError when the step or hook is declared, naming both (Kiln#fire: if: takes a method name (Symbol or String) or a callable, got Integer (5)). If both are present, whichever one asks to skip wins. A step that is skipped this way never runs and leaves no entry in the history. Guard methods can be private, but the missing-method check ignores them, so a misspelled guard raises NoMethodError only when it is evaluated, partway through a run.

class ClearDeparture < Actionable::Action
input { required :vessel, :string }
step :inspect_hull
step :scrub_ballast, if: :ballast_dirty?
step :ring_bell, unless: ->(action) { action.input.vessel.length < 5 }
step :cast_off
def initialize
super
@trail = []
end
private
def ballast_dirty? = false
def inspect_hull = @trail << :inspect_hull
def scrub_ballast = @trail << :scrub_ballast
def ring_bell = @trail << :ring_bell
def cast_off = succeed(@trail.join(','))
end
ClearDeparture.run(vessel: 'Heron II').message # => "inspect_hull,ring_bell"
ClearDeparture.run(vessel: 'Tern').message # => "inspect_hull"
ClearDeparture.steps.to_a[1].options # => {if: :ballast_dirty?}

Declare a step a second time (same kind, same name) and its options are replaced where it stands, so it keeps its first position. step :x and case_step :x count as different steps, and so do on_success :x and always :x, since every hook list is separate.

A subclass takes a copy of the steps, hooks, schemas, declarations, measure and typed_outcomes at creation time. The parent can change afterwards without affecting it, and redeclaring a step in the subclass touches the subclass only. An inherited step can’t be removed, so switch it off with if: or unless:.

class BaseDeparture < Actionable::Action
step :load_deck
step :sound_horn
private
def load_deck = nil
def sound_horn = nil
end
class SilentDeparture < BaseDeparture
step :sound_horn, unless: ->(_action) { true }
end
BaseDeparture.steps.map(&:options) # => [{}, {}]
SilentDeparture.steps.map(&:name) # => [:load_deck, :sound_horn]
SilentDeparture.steps.to_a.last.options.keys # => [:unless]
SilentDeparture.steps.equal?(BaseDeparture.steps) # => false
case_step(value_method, **options) { on(match, target, **opts); default(target, **opts) }

A case step calls the named method (private works), then runs the first branch whose match accepts the returned value. The target is either a method name or an action class, and default takes whatever is left.

Match Accepts
a value values equal to it (==)
an Array any value the Array includes
a Regexp values whose to_s matches

Actionable::ValueMatch.matches?(branch_value, value) is the matcher everything shares. A Range never matches one of its members since it is compared with == only, so spell it (400..499).to_a rather than 400..499. A nil branch matches nil.

class AssignQuay < Actionable::Action
input { required :cargo, :string }
case_step :cargo do
on 'foot', :use_gangway
on %w[car van], :use_ramp
on(/\Acrane/, :use_hoist)
default :use_tender
end
private
def cargo = input.cargo
def use_gangway = succeed('gangway')
def use_ramp = succeed('ramp')
def use_hoist = succeed('hoist')
def use_tender = succeed('tender')
end
AssignQuay.run(cargo: 'van').message # => "ramp"
AssignQuay.run(cargo: 'crane-lift').message # => "hoist"
AssignQuay.run(cargo: 'livestock').message # => "tender"
AssignQuay.steps.first.kind # => :case
Actionable::ValueMatch.matches?((400..499), 450) # => false
Actionable::ValueMatch.matches?((400..499).to_a, 450) # => true

When nothing matches and there is no default, the step does nothing and no error is raised. Branches accept if: and unless: just like steps do. The value alone picks the branch, and only then does its guard decide whether the target runs. If the matched branch’s guard opts out, nothing happens and a later branch is not tried. case_step is built on Steps::Case.define(value_source, **options), and the resulting step answers branches ([match_value, step] pairs) and default_step.

step ChildAction, input: %i[berth], expose: %i[pass]

A nested action amounts to Child.run(berth: @berth). For each name listed in input:, the parent hands over its instance variable of that name as a keyword, and an unset variable goes in as nil. After a success or a skip, the fields the child really set come back to the parent as instance variables, limited by expose:. A field the child never set can’t overwrite what the parent holds.

class HoldBerth < Actionable::Action
input { required :berth, :string }
output { required :held, :boolean }
step :hold
private
def hold = @held = true
end
class IssueBoarding < Actionable::Action
step HoldBerth, input: %i[berth], expose: %i[held]
step :finish
def initialize
super
@berth = 'D2-17'
@deck = 'upper'
end
private
def finish = succeed("held=#{@held} deck=#{@deck}")
end
IssueBoarding.run.message # => "held=true deck=upper"
IssueBoarding.steps.first.kind # => :action

When the child fails, the parent fails too and stops. It takes over the child’s code, message, errors and metadata directly, never passing through its own fail. A parent that declares any failure code has to declare every non-gem code its children can fail with, otherwise DefinitionError is raised, while the gem’s own :invalid_input and :invalid_output pass through freely. A child’s skip doesn’t count as an outcome for the parent, which carries on as it would after a success. If the parent measures, the child’s history is attached to the matching step record (see Hooks and history).

.run goes through these stages in order: build and validate the input (invalid input returns its failure right there), instantiate, check for missing methods, check verb positions on the first run, then run the steps.

  • Missing methods. Each step, hook and case-branch method has to exist on the instance, public or private, and can’t come from Kernel, Object or BasicObject, so step :puts fails. The error is a DefinitionError that names each kind it found: <Action> declares step(s) calling :a, :b and hook(s) calling :c but does not implement them, with after_commit hook(s) for the Rails hooks. A step whose guard would skip it is still checked.
  • Verb position. The first run of a class raises DefinitionError when a plain verb has more code after it. Errors and guardrails has the details.

FieldStruct, Actionable and their adapters are open source under the MIT license.