NAME

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

SYNOPSIS

          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 );
          }

DESCRIPTION

       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.

CONSTRUCTOR

   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 )

       Since version 0.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.

METHODS

   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

       Since version 0.04.

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

   putback_tokens
          $inv->putback_tokens( @tokens )

       Since version 0.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.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>