Input and output
Input and output of an action are both FieldStruct schemas: the input is checked before the first step, the output after the last. Types come from the system described on FieldStruct’s types page. The gem produces two failures on its own, :invalid_input and :invalid_output, and below we say when each appears.
input { |schema_body| ... } # declareinput # read the schema class, or nilThe block holds a FieldStruct body. Action.input_schema reads the same thing, Action.input.new(...) makes an instance, and a subclass shares the schema of its parent. If the action has no input, both the class reader and the step-side input return nil.
.run(**kwargs) builds the struct from the keywords (string keys are fine), checks valid? and gives the steps the struct as input. Values get coerced, so bunks: '12' turns into 12. Keywords the schema doesn’t know are dropped, except under unknown_attributes :raise, where .run raises FieldStruct::UnknownAttributeError itself and no failure is returned.
class FillDeck < Actionable::Action input do required :bunks, :integer optional :remark, :string end
step :load
private
def load = succeed("filled #{input.bunks}")end
FillDeck.run(bunks: '12').message # => "filled 12"bad = FillDeck.run(remark: 'x')bad.code # => :invalid_inputbad.message # => "input failed validation"bad.errors.to_h # => {bunks: ["is required"]}bad.output # => {}FillDeck.input_schema.attribute_names # => [:bunks, :remark]FillDeck.input.equal?(FillDeck.input_schema) # => trueWith invalid input, no step runs. The failure holds the struct’s errors, an empty output and whatever metadata was declared for :invalid_input. An invalid nested struct field reports just the field name with "is invalid".
input_for
Section titled “input_for”input_for(discriminator) { on(match, SchemaClass); default(SchemaClass) }input_for chooses the schema at run time, looking at a single keyword. on accepts a value, an Array of values or a Regexp. The first branch that matches in declaration order wins and default comes last. Matching works exactly as in case steps (see Actions and steps), and the chosen schema is built and validated like a fixed input. If both input and input_for are declared, the dispatch has the final say.
class FreightShape < FieldStruct::Base required :bunks, :integerend
class RebateShape < FieldStruct::Base required :voyage_no, :integerend
class LogManifest < Actionable::Action input_for(:manifest_kind) do on 'freight', FreightShape on %w[rebate refund], RebateShape end
step :log
private
def log = succeed(input.class.name)end
LogManifest.run(manifest_kind: 'freight', bunks: 5).message # => "FreightShape"LogManifest.run(manifest_kind: 'rebate', voyage_no: 1).message # => "RebateShape"LogManifest.run(manifest_kind: 'kraken').message # => "no input shape for manifest_kind \"kraken\""LogManifest.run(manifest_kind: 'kraken').code # => :invalid_inputIf nothing matches and there is no default, the result is Failure(:invalid_input) with the message no input shape for <discriminator> <value.inspect>. An absent discriminator is read as nil. It is looked up by Symbol in the keywords only, so a string key such as 'manifest_kind' finds nothing. One positional instance of any schema the dispatch can reach is accepted as is.
Action.input_dispatch is an InputDispatch (nil without input_for):
| Member | Returns |
|---|---|
discriminator |
the Symbol |
branches |
[match_value, schema] pairs in order |
variants |
the match values in order; %w[rebate refund] stays one entry |
schemas |
the distinct schema classes, branches then default |
default_schema |
the default schema, or nil |
schema_for(value) |
the first matching schema, else the default, else nil |
dispatch = LogManifest.input_dispatchdispatch.discriminator # => :manifest_kinddispatch.variants # => ["freight", ["rebate", "refund"]]dispatch.schema_for('refund') # => RebateShapedispatch.schemas # => [FreightShape, RebateShape]dispatch.branches.first # => ["freight", FreightShape]dispatch.default_schema # => nilinput_for is a thin wrapper over InputDispatch.define(discriminator) { ... }, whose builder offers on and default. For a dispatched action the generated RBS types .run as (*untyped) (see RBS).
output
Section titled “output”output { |schema_body| ... } # declareoutput # read the schema class, or nilNothing but the fields declared in output reaches the result. Once the steps are done, and again after each hook, each declared field is filled from the instance variable with the same name (a variable holding nil still counts as set). Keywords given to succeed beat variables, and the struct is then coerced and validated. Variables and keywords that were never declared are left out. A valid struct becomes result.output, and its fields can be read straight off the result (see Results).
When a success can’t satisfy its output schema, it is swapped for Failure(:invalid_output): the message is output failed validation, the field errors come from the struct, and the invalid struct stays available as output for inspection. Later hooks keep that invalid output instead of rebuilding it. Only a strict success is validated against the success schema.
class SettleFare < Actionable::Action output { required :fare_pence, :integer }
step :settle
private
def settle @fare_pence = nil @scratch = 'never shown' endend
result = SettleFare.runresult.code # => :invalid_outputresult.errors.to_h # => {fare_pence: ["is required"]}result.output.valid? # => falseSettleFare.output_schema.attribute_names # => [:fare_pence]Keywords beat variables, and the schema coerces the values:
class CountDecks < Actionable::Action output do required :decks, :integer required :tag, :string end
step :count
private
def count @decks = '2' @tag = 7 succeed(decks: 4) endend
CountDecks.run.decks # => 4CountDecks.run.tag # => "7"With no output schema the output is whatever succeed received (a Hash, {} if nothing), and fields are not delegated. A failure or skip grabs the declared variables that were set up to that point, as a best effort, without validating and without adding an output error. A failure code with its own schema is built from the keywords it was given and nothing else (see Declared outcomes). A hook that sets a variable named like an output field is picked up by the next refresh, which means a hook can break an output that was valid before.
Reserved output names
Section titled “Reserved output names”Output fields can’t share a name with a result attribute (code, message, output, history, errors, metadata), a reserved action name (result, input) or any public Result method (status, ok?, to_h, output_fields_set, absorb_errors_from, and so on). Declaring one raises Actionable::DefinitionError right away: Result methods always win, so the gem refuses any ambiguity. Input field names aren’t guarded, because they are read as input.x.
begin Class.new(Actionable::Action) { output { required :status, :string } }rescue Actionable::DefinitionError => e e.message.include?(':status') # => trueendSee also
Section titled “See also”- Declared outcomes: per-code output schemas
- FieldStruct types: what you can declare inside the block
- Results:
output_fields_setand delegation
FieldStruct, Actionable and their adapters are open source under the MIT license.