"Commandable::Invocation" - represents one invocation of a CLI command

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.40.0                                       2024-09-08                       Commandable::Invocation(3pm)

new
          $inv = Commandable::Invocation->new( $text )

       Constructs a new instance, initialised to contain the given text string.

   new_from_tokens
          $inv = Commandable::Invocation->new_from_tokens( @tokens )

       Sinceversion0.03.

       Constructs a new instance, initialised to contain text from the given tokens, such that subsequent calls
       to "pull_token" will yield the given list of tokens. This may be handy for constructing instances from
       @ARGV or similar cases where text has already been parsed and split into tokens.

       Instances of this class represent the text of a single invocation of a CLI command, allowing it to be
       incrementally parsed and broken into individual tokens during dispatch and invocation.

   Tokens
       When parsing for the next token, strings quoted using quote marks ("") will be retained as a single
       token. Otherwise, tokens are split on (non-preserved) whitespace.

       Quote marks and backslashes may be escaped using "\" characters.

peek_token
          $token = $inv->peek_token;

       Looks at, but does not remove, the next token in the text string. Subsequent calls to this method will
       yield the same string, as will the next call to "pull_token".

   pull_token
          $token = $inv->pull_token;

       Removes the next token from the text string and returns it.

   peek_remaining
          $text = $inv->peek_remaining;

       Sinceversion0.04.

       Returns the entire unparsed content of the rest of the text string.

   putback_tokens
          $inv->putback_tokens( @tokens );

       Sinceversion0.02.

       Prepends text back onto the stored text string such that subsequent calls to "pull_token" will yield the
       given list of tokens once more. This takes care to quote tokens with spaces inside, and escape any
       embedded backslashes or quote marks.

       This method is intended to be used, for example, around a commandline option parser which handles mixed
       options and arguments, to put back the non-option positional arguments after the options have been parsed
       and removed from it.

       "Commandable::Invocation" - represents one invocation of a CLI command

          my %commands = (
             exit  => sub { exit },
             print => sub { print $_[0]->peek_remaining },
             ...
          );

          while(1) {
             my $inv = Commmandable::Invocation->new( scalar <STDIN> );

             $commands{ $inv->pull_token }->( $inv );
          }