Composing actions
ReservePlaces is about to grow. A trek also needs a shuttle to the trailhead and, now and then, a porter for the heavy packs. In this chapter we split the work into small actions and let a PlanTrek action run them in order.
Where we left off
Section titled “Where we left off”We had one action that checked and took free places. Here that part stands alone, next to a table of shuttle times and a table of porter loads.
FREE = { 'KR12' => 3 }SHUTTLES = { 'north' => 35, 'east' => 80 }PORTERS = { 'LIGHT' => 8, 'FULL' => 20 }
class TakePlaces < Actionable::Action input do required :hut_code, :string required :places, :integer end
output do required :remaining, :integer end
fails :fully_booked, 'not enough places free'
step :check step :take
private
def check fail!(:fully_booked) if FREE.fetch(input.hut_code, 0) < input.places end
def take FREE[input.hut_code] -= input.places @remaining = FREE[input.hut_code] endend
class ChooseTrailhead < Actionable::Action input { required :valley, :string } output { required :shuttle_minutes, :integer }
fails :no_shuttle, 'no shuttle serves that valley'
step :pick
private
def pick minutes = SHUTTLES[input.valley] fail!(:no_shuttle) unless minutes @shuttle_minutes = minutes endend
class AddPorter < Actionable::Action input { optional :porter_code, :string } output { optional :porter_kg, :integer }
skips :no_porter
step :assign
private
def assign skip!(:no_porter) if input.porter_code.nil? @porter_kg = PORTERS.fetch(input.porter_code, 0) endendEach one runs alone, and each is easy to test.
ChooseTrailhead.run(valley: 'east').shuttle_minutes # => 80ChooseTrailhead.run(valley: 'west').code # => :no_shuttleAddPorter.run.skipped? # => trueAn action as a step
Section titled “An action as a step”A step can name an action class instead of a method. The parent passes values by naming instance variables with input:, and takes outputs back as instance variables, narrowed with expose:.
class PlanTrek < Actionable::Action input do required :hut_code, :string required :places, :integer required :valley, :string optional :porter, :string end
output do required :remaining, :integer required :shuttle_minutes, :integer optional :porter_kg, :integer end
fails :fully_booked, 'not enough places free' fails :no_shuttle, 'no shuttle serves that valley'
step :prepare step TakePlaces, input: %i[hut_code places], expose: %i[remaining] step ChooseTrailhead, input: %i[valley], expose: %i[shuttle_minutes] step AddPorter, input: %i[porter_code], expose: %i[porter_kg]
private
def prepare @hut_code = input.hut_code @places = input.places @valley = input.valley @porter_code = input.porter endendThe prepare step copies the typed input into instance variables, since that’s what child steps read. Let’s run it.
done = PlanTrek.run(hut_code: 'KR12', places: 1, valley: 'east', porter: 'LIGHT')
done.success? # => truedone.remaining # => 2done.shuttle_minutes # => 80done.porter_kg # => 8A child skip does not stop the parent
Section titled “A child skip does not stop the parent”With no porter requested, AddPorter skips. The parent carries on, as it would after a success.
plain = PlanTrek.run(hut_code: 'KR12', places: 1, valley: 'north')
plain.success? # => trueplain.porter_kg # => nilplain.shuttle_minutes # => 35FREE['KR12'] # => 1A skip means “nothing to do here”. The parent doesn’t have to handle it.
A child failure becomes the parent’s
Section titled “A child failure becomes the parent’s”Asking for more places than are free makes TakePlaces fail, and PlanTrek fails with the same code.
full = PlanTrek.run(hut_code: 'KR12', places: 5, valley: 'north')
full.failure? # => truefull.code # => :fully_bookedfull.message # => "not enough places free"Because PlanTrek declares failures, it has to declare every code its children can fail with. Leave out :no_shuttle and the first run where the shuttle child fails raises Actionable::DefinitionError, naming the code.
Undo with on_failure
Section titled “Undo with on_failure”Here is a real problem. When the valley has no shuttle, TakePlaces already took a place, and nobody can reach the hut. An on_failure hook runs after a failed run, so we give the place back.
class PlanTrek on_failure :release_places
private
def release_places FREE[@hut_code] += @places if @remaining endend
before = FREE['KR12']stuck = PlanTrek.run(hut_code: 'KR12', places: 1, valley: 'west')
stuck.code # => :no_shuttleFREE['KR12'] == before # => trueThe hook ran only because the run failed, and @remaining is set only when TakePlaces got far enough to succeed. After a :fully_booked failure nothing was taken, so there is nothing to give back.
See what ran
Section titled “See what ran”An action that measures keeps a history of every step.
class PlanTrek measure :allend
traced = PlanTrek.run(hut_code: 'KR12', places: 1, valley: 'north')traced.history.steps.size # => 4traced.history.steps.map(&:section).uniq # => [:main]traced.history.took.class # => FloatThe four entries are prepare and the three child actions, and no :failure entry shows up because nothing failed. Each entry names the section (:main for steps, :failure for the undo hook), the step and how long it took. Measuring is off by default, so a normal run pays nothing.
What you built
Section titled “What you built”Three small actions and a PlanTrek that composes them. A child skip let the parent go on, a child failure became the parent’s, an on_failure hook returned the place, and history showed what ran.
Next we take the trek planner into an app.
See also
Section titled “See also”- Into an app: the next chapter
- Compose actions
- Hooks and history
- Actions and steps
FieldStruct, Actionable and their adapters are open source under the MIT license.