Net::C...Engine(3pm)

🌸 Net::CLI::Interact::Role::Engine — bestie edition 💅

okay so you found the Net::CLI::Interact::Role::Engine page in the User Contributed Perl Documentation, and honestly? you've arrived at the main character of the whole show. let's get into it 🫶

---

✨ NAME ✨

Net::CLI::Interact::Role::Engine — the statement execution engine, no cap 👑

---

💖 DESCRIPTION 💖

this module is literally the core of Net::CLI::Interact. like, the whole point. what does it do? it takes entries from your loaded Phrasebooks, yeets them at your connected devices, and gathers up whatever output comes back. that's the gig. that's the whole vibe. 🦋

---

🎀 INTERFACE 🎀

⭐ cmd( $command_statement, \%options? )

runs a single command statement on the connected device, then keeps consuming output until it matches the current prompt. the statement goes out verbatim on the device, with a newline tacked onto the end. (yes, verbatim. we don't editorialize. we deliver. 💅)

here's the options it fucks with:

• timeout => $seconds (optional) — sets a timeout value for the Transport that's local to this cmd call only. it overrides whatever the Transport has set, and it overrides the default of 10 seconds. lowkey powerful ngl.
• no_ors => 1 (optional) — pass a true value and a newline character (well, technically the value of ors) will not be appended to the statement sent to the device. sometimes you just don't want the newline, bestie, and that's valid 🫶
• match => $name | $regexpref | \@names_and_regexprefs (optional) — lets this one command only finish with a custom match. it has to be one or more of: the name of a loaded phrasebook Prompt, or your very own regular expression reference (qr//). on a successful match, the module updates the current prompt to be that same value. iconic behaviour honestly.

so, context matters here and it's giving ✨dual purpose✨:

• in scalar context you get the last_response back (more on that below).
• in list context you get the gathered response as a list of lines.
• either way, your local platform's newline character will end all the lines. periodt.

🌈 macro( $macro_name, \%options? )

runs all the commands tucked inside the named Macro, which — important — must be loaded from a Phrasebook. any options for controlling output, including variables for substitution into the Macro, get passed in that %options hash reference.

options, incoming:

• params => \@values (optional) — if the Macro has commands using sprintf Format variables, then the matching parameters must be passed in this value as an array reference. values get consumed from that array reference and handed to the send commands in the Macro, in order, as needed. and listen — an exception will be thrown if there aren't enough parameters. so don't skimp. 💀
• timeout => $seconds (optional) — same deal as before but for macro: sets a timeout for the Transport local to this call, overriding whatever the Transport has set, or the default of 10 seconds.

⚠️ heads up: an exception will be thrown if the Match statements in the Macro don't succeed against the output returned from the device. this whole thing is governed by the value of timeout, which controls how long the module waits around for matching output. patience has a limit, and that limit is configurable. 😭

and same context rules as cmd, because consistency is the vibe:

• scalar context → last_response comes back.
• list context → gathered response as a list of lines.
• both cases → your local platform's newline character ends all the lines. 💜

🦋 last_response

gives you back the gathered output from after the last recent send command within the most recent cmd or prompt. in other words: you get the output from the last command sent to the connected device. that's it. that's the tea. 🍓

• scalar context → all data is returned.
• list context → gathered response as a list of lines.
• both cases → your local platform's newline character will end all the lines.

👑 last_actionset

returns the complete ActionSet that got constructed from the most recent macro or cmd execution. this is gonna be a sequence of Actions that correspond to send and match statements.

here's the breakdown so you're not confused:

• for a Macro: these directly relate to the contents of your Phrasebook, possibly with some match statements added automatically. surprise bonus content 🎁
• for a cmd execution: an "anonymous" Macro gets constructed, and it consists of exactly one send and one match. minimal. efficient. slay.

---

🧚 COMPOSITION 🧚

want even more interface details? go peek at this:

• Net::CLI::Interact::Role::Prompt

---

💫 sign-off 💫

that's the whole page bestie, mwah 💋 — brought to you by perl v5.36.0, dated 2023-10-28. go forth and match some prompts. 🎀✨