Comman...ocation(3pm)

💖 Comman...ocation(3pm) 💖

okay bestie, this is a page from the User Contributed Perl Documentation, and today we're learning about Commandable::Invocation, which is giving very much "one CLI command, one moment in time" energy. 🎀

---

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

not me noticing Commmandable has three m's in that synopsis... it's literally in the original, bestie, I'm not touching it 💀

---

✨ DESCRIPTION ✨

So basically, instances of this class are little containers for the text of a single invocation of a CLI command. 🌸 The whole point is that you can incrementally parse it and break it down into individual tokens while you're doing dispatch and invocation. It's giving "unpack the sentence as you go" energy and honestly? obsessed. ✨

🌈 Tokens

When it's parsing for the next token, strings that are quoted using quote marks ("") get retained as a single token — no splitting, no drama. 💅 Otherwise, tokens get split on whitespace, and that whitespace is not preserved. bye bye spaces.

Quote marks and backslashes can be escaped using \ characters. 👑

---

✨ CONSTRUCTOR ✨

🦋 new

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

Constructs a new instance, initialised to contain the given text string. that's it, that's the whole vibe 💖

🦋 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, in such a way that subsequent calls to pull_token will yield the given list of tokens. 🔥 This is handy for constructing instances from @ARGV or similar cases where the text has already been parsed and split into tokens — like when somebody already did the hard work for you. king behaviour, honestly. 👑

---

✨ 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, and so will the next call to pull_token. it's the "look but don't touch" of token parsing. no cap.

💜 pull_token

$token = $inv->pull_token;

Removes the next token from the text string and returns it. gone. snatched. 💅

💜 peek_remaining

$text = $inv->peek_remaining;

Since version 0.04.

Returns the entire unparsed content of the rest of the text string. ✨ the leftovers, the rest of the sentence, everything still sitting there untouched. main character energy.

💜 putback_tokens

$inv->putback_tokens( @tokens );

Since version 0.02.

Prepends text back onto the stored text string, in such a way that subsequent calls to pull_token will yield the given list of tokens once more. 🔁 It's very careful about this too — it takes care to quote tokens that have spaces inside, and to escape any embedded backslashes or quote marks. so polite. so considerate. 🎀

This method is intended to be used, for example, around a commandline option parser which handles mixed options and arguments — so you can put back the non-option positional arguments after the options have been parsed and removed from it. 🫶 literally the "wait, come back" of argument parsing.

---

✨ AUTHOR ✨

Paul Evans <leonerd@leonerd.org.uk> 👑

---

aaaand that's the whole page bestie, we ate and left no crumbs 💖✨🌸 the manual name up top is Comman...ocation(3pm) (yeah, the title got truncated like that, iconic honestly), and this came from perl v5.40.0, dated 2024-09-08. go forth and tokenise responsibly 🦋💅🎀