9. Inventory in C++#

For: C++ programmers (advanced). Needs: Tutorials 5 and 8. You will: read the ZagalaSpecExamples design behind the Inventory feature: a setup step that resets its system in teardown, a step that reads raw capture text, a one-line examples iterator, value-store data types and the DSL/driver split.

This page describes what each class does and why. The full source ships in the installed plugin under Source/ZagalaSpecExamples/Public/Inventory/, Source/ZagalaSpecToolkit/Public/ and the matching Private/ folders; open it alongside this page.

Class map#

        flowchart LR
    subgraph Context extensions
        CE1["UZagalaSpecCEEmptyInventory"]
        CE2["UZagalaSpecCEFocusItem"]
        CE3["UZagalaSpecCELoadDefaultStock"]
        CE4["UZagalaSpecCEInventoryIterator"]
    end
    subgraph Expectations
        S1["UZagalaSpecStepAddItemByAmount<br/>UZagalaSpecStepAddItemDirectly<br/>UZagalaSpecStepAddFocusedItemAndQty"]
        S2["UZagalaSpecStepAssertInventoryCount<br/>UZagalaSpecStepAssertInventoryCountFromCache<br/>UZagalaSpecStepAssertFocusedQty"]
    end
    S1 --> D1["UZagalaSpecDSLAddItem"] --> P1["UZagalaSpecPDAddItem"]
    S2 --> D2["UZagalaSpecDSLAssertInventoryItem"] --> P2["UZagalaSpecPDAssertInventoryItem"]
    P1 --> SUT["UZagalaSpecExamplesInventory"]
    P2 --> SUT
    CE1 -- "InventoryRef" --> Cache[("cache")]
    CE2 -- "ItemName" --> Cache
    CE4 -- "ItemName + Integer per row" --> Cache
    

Sentence

Step entry pattern

Class

Given a fresh empty inventory

^(?:Given |And )?a fresh empty inventory$

UZagalaSpecCEEmptyInventory

Given I focus on item "Sword"

^(?:Given |And )?I focus on item "([^"]+)"$

UZagalaSpecCEFocusItem

Given the default stock is loaded

^(?:Given |And )?the default stock is loaded$

UZagalaSpecCELoadDefaultStock

Given iterate over inventory <Examples>

^(?:Given |And )?iterate over inventory <(.+)>$

UZagalaSpecCEInventoryIterator

When I add 3 of that item

^(?:When |And )I add (\d+) of that item$

UZagalaSpecStepAddItemByAmount

When I add 10 of "Arrow" directly

^(?:When |And )I add (\d+) of "([^"]+)" directly$

UZagalaSpecStepAddItemDirectly

When I add the focused item and quantity

^(?:When |And )I add the focused item and quantity$

UZagalaSpecStepAddFocusedItemAndQty

Then the inventory has 3 of "Sword"

^(?:Then |And )the inventory has (\d+) of "([^"]+)"$

UZagalaSpecStepAssertInventoryCount

Then the inventory has 3 of that item

^(?:Then |And )the inventory has (\d+) of that item$

UZagalaSpecStepAssertInventoryCountFromCache

Then the inventory has the focused quantity of that item

^(?:Then |And )the inventory has the focused quantity of that item$

UZagalaSpecStepAssertFocusedQty

Tagged data: UZagalaSpecDataInventoryRef (holds the SUT), UZagalaSpecDataItemName (ZagalaSpec.DSL.Data.Examples.Inventory.ItemName), and the shared UZagalaSpecDataInteger (…Toolkit.Integer) for quantities.

The system under test#

UZagalaSpecExamplesInventory is a UObject with a TMap<FString, int32>: AddItem(Name, Quantity) returns false for non-positive quantities, GetCount(Name) returns 0 for unknown items, Reset() clears. It has no idea ZagalaSpec exists. Keep your SUTs like this; the drivers are the adapter.

Setup that cleans up after itself#

UZagalaSpecCEEmptyInventory (a UZagalaSpecDefaultExecutionStep) owns two responsibilities:

UPROPERTY(Transient)
TScriptInterface<IZagalaSpecTaggedDataCacher> AssignedCacherReference;

virtual void InternalExecute_Implementation(const TScriptInterface<IZagalaSpecTaggedDataCacher>& AssignedCacher) override;
virtual void InternalTeardown_Implementation() override;
  • Execute: remember the cacher, create a UZagalaSpecExamplesInventory and a UZagalaSpecDataInventoryRef pointing at it, store the ref with UZagalaSpecTaggedDataHandler::SetDataT, broadcast success.

  • Teardown: look the ref up again through the remembered cacher and call Reset() on the inventory.

Why the teardown matters: in the iterator scenario this extension’s link object is reused on every pass. The cache is cleared between passes, so a fresh InventoryRef is written each time, but resetting the SUT in teardown is the habit that keeps any state you own from leaking: actors, subsystems, timers. Create the SUT and its ref with the cache’s owner as outer so they live exactly as long as the context does.

Reading capture text without a tagged data class#

UZagalaSpecCEFocusItem does not call AddLocalSetupDataToCache. It overrides two methods:

virtual void Setup_Implementation(FZagalaSpecExecutionStepData StepData) override;
virtual void InternalExecute_Implementation(const TScriptInterface<IZagalaSpecTaggedDataCacher>& AssignedCacher) override;

In Setup it calls Super, then reads StepData.CaptureGroupCustomizer->GetCaptureGroup(0)->GetCaptureGroupValue() into a cached string. In InternalExecute it creates a UZagalaSpecDataItemName, fills ItemName from that string, stores it and broadcasts success.

Configurators never set a Group Value Class on this step; the step decides. Use this form when the step is the only consumer of its own text. Use AddLocalSetupDataToCache when the converted value should be available to DSL actions and drivers, or when configurators should be able to swap the class (Global scope, Blueprint subclasses).

A one-line iterator#

UCLASS(Blueprintable, EditInlineNew)
class ZAGALASPECEXAMPLES_API UZagalaSpecCEInventoryIterator : public UZagalaSpecContextExtensionExamplesIterator
{
    GENERATED_BODY()
};

That is the whole class. UZagalaSpecContextExtensionExamplesIterator already implements IZagalaSpecIterationController, loads the examples asset from its first capture group’s Group Value Object, writes the current row’s tagged data each pass, and resets its index in teardown. The subclass exists only so the Inventory feature can have its own sentence (iterate over inventory <…>) via UZagalaSpecExamplesStepEntryInventoryIterator. The core sentence Given examples from <…> maps to the base class directly.

If you need custom per-row behaviour, override InternalExecute_Implementation, call Super, then read the row’s data back from the cache.

Value-store data types#

Quantities use the shared UZagalaSpecDataInteger: a UZagalaSpecTaggedData that also implements IZagalaSpecValueStore, with one int32 Value property. Its StoreValue_Implementation parses the captured text with FCString::Atoi, and GetLoadTag() returns ZagalaSpec.DSL.Data.Toolkit.Integer.

IZagalaSpecValueStore is what lets the default converter turn "3" into this object when a capture group’s Group Value Class is set to it. UZagalaSpecDataItemName and UZagalaSpecDataString follow the same shape with an FString. Subclasses that only change the tag (UZagalaSpecDataTickLimit, UZagalaSpecDataWaitTicks, Counter’s UZagalaSpecDataCounterAmount) override GetLoadTag() and nothing else: one integer type, many meanings, no collisions because each has its own tag.

Because the cache holds one object per tag, Then the inventory has 3 of "Sword" and When I add 3 of that item both write the shared Integer tag. That is intended here; if two values must coexist, give them distinct tagged data classes, as Counter does with Amount, Expected and Value.

Steps, DSL and driver#

The three add steps are UZagalaSpecChainLinkOnStep subclasses that differ only in what they capture:

Step

Captures

Reads from cache

UZagalaSpecStepAddItemByAmount (I add (\d+) of that item)

[0] → UZagalaSpecDataInteger

item name

UZagalaSpecStepAddItemDirectly (I add (\d+) of "([^"]+)" directly)

[0] → Integer, [1] → UZagalaSpecDataItemName

nothing

UZagalaSpecStepAddFocusedItemAndQty

nothing

item name and quantity (from the iterator row)

Each one follows the Tutorial 3 shape: create the DSL action into Action, subscribe, call AddLocalSetupDataToCache if it has capture groups, execute. UZagalaSpecStepAddFocusedItemAndQty wraps the DSL in a UZagalaSpecDefaultExecutionChainer via AddLinkT, which is the form to start from when a step will grow to several DSL actions.

All three reach the same driver through UZagalaSpecDSLAddItem, a pass-through UZagalaSpecChainLinkOnChainLink. UZagalaSpecPDAddItem validates every input before touching the SUT and names what is missing: InventoryRef not found or invalid, ItemName not found, Integer (qty) not found. Only then does it call Inventory->AddItem(Name, Quantity), broadcasting success or AddItem returned false for '%s' qty=%d.

UZagalaSpecPDAssertInventoryItem is the read-side twin and ends with the message stakeholders actually see: Expected %d of '%s', but found %d.

What to copy#

  • A setup extension that creates the SUT, stores a ref, and resets it in InternalTeardown_Implementation.

  • One integer type per meaning: subclass UZagalaSpecDataInteger and override GetLoadTag().

  • Drivers that validate first: every missing input is a distinct, searchable failure string.

  • Iterator by subclassing when you want a project-specific sentence; otherwise reuse Given examples from <…>.

Next: 10. Hoverboard in C++ adds a world, physics and latent waits.