Packs

A pack is a gem that pairs fixed mechanics in Ruby with a definition people can edit, and adds its own shelf of shipped blueprints.

After reading this guide, you will know:

• What a pack is, and how it differs from a blueprint.
• How a pack registers itself with Studio.
• What a pack’s definition, template and trial do.
• How a gem adds a shelf of shipped blueprints.

Mechanics in Code, Definitions as Data

A pack pairs fixed mechanics in Ruby with a definition a user can edit. The mechanics are code because they change rarely and are hard to express as data (splitting time, walking a tree); the definition is data because it changes often (rates, rules, thresholds). A pack’s mechanics never hard-code its definition’s values.

Blueprints are the pack that ships with Studio. Any gem can add more. Studio and the engine never name a pack: a pack registers itself.

flowchart LR
    yaml["definition<br/>YAML, JSON or a hash"] --> from_h["definition.from_h<br/>numbers to BigDecimal, dates to Date"]
    from_h --> errors{"definition.errors"}
    errors -->|"problems"| invalid["InvalidDefinition<br/>every problem in plain words"]
    errors -->|"none"| template["template<br/>built once from the published version"]
    template --> use["trial.call(template, facts)"]

Registering a Pack

Once Studio is loaded, a gem registers a pack type, any starting points, and a shelf of shipped blueprints:

require 'reckoning/studio'

Reckoning::Studio.register_pack 'dice', Reckoning::Studio::PackType.new(
  label: 'Dice', definition: Dice::Definition, template: Dice::Template.method(:new), trial: Dice::Trial,
  javascript: 'dice/studio_pack'
)
Reckoning::Studio.register_starter('dice/d6', 'Dice: a plain d6') { {sides: 6} }
Reckoning::Blueprint.shelves << File.expand_path('blueprints', __dir__)

A starter’s key is pack/name, and its block returns a draft for that pack.

Definitions

A definition loads from JSON-safe data: string keys, numbers and dates as strings. from_h turns them into symbols, BigDecimal and Date. Building a template validates the definition and raises Reckoning::InvalidDefinition, whose errors lists every problem in plain words:

Reckoning::InvalidDefinition.check(errors)   # raises when errors is not empty

Studio shows those problems in the editor and refuses to publish while there are any.

Shelves

A shelf is a directory of name/blueprint.yml folders, each with its cases.yml and a README beside it. Blueprint.shipped(:name) and Studio’s Blueprints page read every shelf, so a gem’s blueprints work exactly like the ones that ship with Reckoning:

Reckoning::Blueprint.shelves << File.expand_path('blueprints', __dir__)
Reckoning::Blueprint.shipped(:my_plan)          # from the gem's shelf
Reckoning::Blueprint.shipped_names              # every shelf's names

A blueprint on a shelf can import others by name, so a pack’s blueprints can build on the shipped ones.

A pack can also register custom steps (see Custom Steps) when it loads, so its shipped blueprints can use them. That is the one way Ruby steps reach a hosted service: packs installed with it.

Without Studio

A pack’s blueprints and steps need only require 'reckoning'. Load the pack’s plain entry point (one that does not require Studio) to use them in a script or a service; a pack’s Ruby mechanics can hand rows to a shipped blueprint as facts.

The CLI cannot run a pack’s own definitions yet. A pack feeds a blueprint from Ruby today.

Where Packs Are Heading

New domains climb a ladder as they prove themselves: a blueprint built by an agent with its cases, then a part shared by several blueprints, then a custom step promoted into a gem, then a pack with its own editor and starting points. The aim is that a pack becomes a blueprint built from promoted steps, with an editor on top.

Next Steps

• Studio - Where a pack’s editor runs.
• Custom Steps - Ruby steps a pack can register.
• Shipped Blueprints - The shelf that ships with the gem.