Ferreteria/v0.6/clade/Sys/Events/InputRq

clade: Sys\Events\InputRq

Clade Family ItWent[i,t] → InputRq → Setting Clade Aliases Alias Clade Base* [c,i] Aux\StandardBase HasStatus* [i,t] Sys\Events\has\ItWent InData* [c,i] Sys\Events\InputRq\aux\InRqData ItemIface Sys\Events\InputItem PieceIface Sys\Data\Things\Array\aux\Piece SelfIface Sys\Events\InputRq Subpages @fx/WithItemPiece @removed Settable Setting Setting/@fx/Describe Setting/@fx/Go Setting/@removed aux/InRqData aux/InRqData/@history aux/InRqData/@retired aux/InRqData/@thinking

About

• Purpose: set of action-classes for handling user input parameters as a sequence of actions
  • These can then be described, acted on, or both.
• Note: Not to be confused with:
  • Action: the generic action-result base clades
  • Sys\Data\reqs\Engine\CommRq - Database communication (data-xfer) requests
  • Sys\Data\reqs\Engine\AdminRq - Database administration requests

System

This is part of the system whereby CLI input is parsed into future actions (`caActor` podlings), which at go-time are converted into fully-provisioned requests (e.g. Sys\Data\reqs\Engine\AdminRq podlings).

History

• 2024-10-27 (re?)started -- I have a distinct memory of writing somethng like this only a few weeks ago, but I cannot find it anywhere.
• 2024-11-19 renamed/moved from Sys\Routing\Action ⇒ Sys\Events\Actor.
• 2025-01-22 I tried to both rename this clade and combine it with the AdminRq/CommRq clades, but the combining part didn't work out.
  • It still needs renaming, though -- so trying the less ambitious measure of renaming Actor -> InputRq.
• 2025-09-27 added Config\Roster\for\AnObject as trait to provide WithSlug() function, but this is really more of a guess than a "yes, this is appropriate".

Thinking

• 2024-10-27 Since I remember writing this but can't find it, I have to wonder if I did write it and then decide it was redundant.
  • One reason I might have decided it's redundant is: instead of creating an object for each action parsed out of the input, why not just Do The Thing? Being able to handle the action-plan in different ways, though, is much easier if you're not dealing with that fork at the same time as you're parsing them out of the input. It's easier to juggle ten plates if you do them five at a time.
  • (2024-12-15) I think the final deciding factor was that we don't have all the pieces we need when the Actor is created at parse-time -- the database object only becomes available sometime after the command is parsed. So we need an object that can remember what to do without having to do it right away.

Functions

name	type	notes
Describe()	abstract public	usually defined at the application-input level (e.g. DoExport)
ParseInputArgs()	abstract protected	typically defined at the application level (e.g. InReq) also defined by Setting for inputs that map directly to value-names
ParseInputString()	abstract protected	typically defined at the application level (e.g. InReq) also defined by Setting for inputs that map directly to value-names
WithItemPiece()	protected	calls $this->ParseInputArgs(), $this->ParseInputString()

Code

• Repository: v0.6-dev
• @removed
• as of 2025-11-19:

interface iInputRq extends BaseIface, HasStatusIface {
    // CONFIG
    function NameOfInput() : string;
    // SETUP
    function Item(ItemIface $o=NULL) : ItemIface;
    // ACTION
    function Go();
    // INFO
    function Describe() : string;
}
abstract class caInputRq extends BaseClass implements SelfIface {
    use HasStatusTrait;

    // ++ CONFIG ++ //

    // OVERRIDE
    protected function QVarClass(int|string $snKey) : string { return InDataClass::class; }
    // This tells the clade where to store the Singleton object for this podling-class-family.
    static protected function InputClass() : string { die(self::PromptForMethod('Define this in the root InputRq for the command.')); } // DEFAULT
    public function NameOfInput() : string { return $this->Item()->SName(); }

    // -- CONFIG -- //
    // ++ SETUP ++ //

    protected function __construct(){}

    static public function FromItemPiece(ItemIface $oItem, PieceIface $oPiece) : SelfIface {
        $oThis = new static;
        $oThis->WithItemPiece($oItem,$oPiece);
        return $oThis;
    }

    // ++ SETUP: dynamic ++ //

    // DOCS: https://wooz.dev/Ferreteria/v0.6/fx/WithItemPiece
    protected function WithItemPiece(ItemIface $oItem, PieceIface $oPiece) : void {
        $this->Item($oItem);
        if ($oPiece->HasValue()) {
            $sVal = $oPiece->Value();
            $this->ParseInputArgs($oPiece->GetExtras());
        } else {
            // check for default (used if request is present but with no value):
            $osDef = $oItem->SDefault(); // TODO: Implement as $this->Attrs()->QryIt('valdef');
            if ($osDef->HasIt()) {
                $sVal = $osDef->GetIt();
            } else {
                $sVal = '';
            }
        }
        $this->ParseInputString($sVal);
    }

    // NOTE: Basically identical to Events/Actor/Option::Item()
    private $oItem = NULL;
    public function Item(ItemIface $o=NULL) : ItemIface {
        if (is_object($o)) {
            self::HardAssert(is_null($this->oItem),'changing the item-object on an already-configured Action (should probably never happen)');
            // If we ever *actually* need to do this, we need to un-register and re-register.
            $this->oItem = $o;
        } else {
            $o = $this->oItem;  // return previously-set object
        }
        return $o;
    }

    // -- SETUP -- //
    // ++ DATA ++ //

    static private $oaInThis = NULL;
    protected function OAUserInput() : InDataIface { return self::$oaInThis ?? (self::$oaInThis = $this->NewUserInput()); }
    protected function NewUserInput() : InDataIface {
        $oa = (static::InputClass())::AsNew();
        return $oa;
    }

    abstract protected function ParseInputString(string $s) : void;
    abstract protected function ParseInputArgs(array $ar);

    // -- DATA -- //
}