Net::C...t::Base(3pm)

💖 Net::C...t::Base(3pm) 💖

okay bestie, welcome to the manual page for Net::C...t::Base(3pm) — from the User Contributed Perl Documentation era, and yes the manual name is literally spelled Net::C...t::Base(3pm) in the header, we don't make the rules. It's the base class for the whole Transport situation, and it's giving cross-platform CLI vibes. 🦋

---

✨ NAME ✨

Net::CLI::Interact::Transport::Base — Spawns an Interactive CLI Session 🎀

---

🌸 DESCRIPTION 🌸

So this module is a generic cross-platform API whose whole purpose in life is interacting with a command line interface. That's it, that's the job. 💅

On Windows the IPC::Run module is used. On Unix, when IO::Pty is available (and heads up, it requires a compiler, so like, a whole build step, ngl) it uses Net::Telnet, otherwise IPC::Run. Either way — every case, no exceptions — a program such as openssh gets started, and methods are provided to send and receive data from the interactive session. ✨

Do not use this class directly, bestie. Instead you inherit from it in a specific Transport, and that Transport sets the application command line name and marshalls any runtime options. The OS platform is detected automatically, so you don't have to do the detective work. 🕵️♀️

---

👑 INTERFACE 👑

🧚 init

This method must be called before any other one, because it bootstraps the application wrapper module (IPC::Run or Net::Telnet). But plot twist: if you go through Net::CLI::Interact's cmd, match or find_prompt, it gets called for you automatically. main character energy, it just shows up. ✨

Two attributes of the specific loaded Transport are used here. First, the Application set in app is of course required. Plus, the options in the Transport's runtime_options are retrieved — if set — and passed as command line arguments to the Application.

🧚 connect_ready

Returns True if connect has been called successfully, otherwise returns False. Simple as. ✅

🧚 disconnect

Undefines the application wrapper and flushes any output data buffer, such that the next call to cmd or macro will cause a new connection to be made. Super useful if you intentionally timeout a command and end up with junk sitting in the output buffer. 🧹✨

🧚 do_action

When you pass it a Net::CLI::Interact::Action instance, it will execute the contained instruction on the connected CLI. That might be a command to send, or a regular expression to match in the output.

Features of the commands and prompts are supported, such as Continuation matching (and slurping 🥤), and sending without an output record separator.

On failing to succeed with a Match, the module will time-out (see timeout, below) and raise an exception. 😭

Output returned after issuing a command is stored within the Match Action's response and response_stash slots by this method, with the latter then marshalled into the correct send Action by the ActionSet. iconic behaviour tbh. 💅

🧚 put( @data )

Items in @data are joined together by an empty string and sent as input to the connected program's interactive session. that's the whole thing. 🫶

🧚 pump

Attempts to retrieve pending output from the connected program's interactive session. Returns true if there is new data available in the buffer, else will time-out and raise a Perl exception. See buffer and timeout. 😤

🧚 flush

Empties the buffer used for response data returned from the connected CLI, and returns that data as a single text string (possibly with embedded newlines). one string, all the data, no crumbs left. 🍓

🧚 timeout( $seconds? )

When do_action is polling for response data matching a regular expression Action, it will eventually time-out and throw an exception if nothing matches and no more data arrives.

The number of seconds to wait is set via this method, which will also return the current value of timeout. The default value is 10 seconds. ⏰

🧚 irs_re

Returns the Regular Expression reference used to split lines of response from the connected device. In the end, you will only receive data from this module separated by the ors value (by default a newline character). The irs_re is used internally by the module and is:

qr/(?:\015\012|\015|\012)/  # i.e. CRLF or CR or LF

iykyk. 💀

🧚 ors

Line separator character(s) appended to a command sent to the connected CLI. This defaults to a newline on the application's platform. 🌈

🧚 logger

Slot for storing a reference to the application's Logger object. 📓

🧚 is_win32

Returns true if the current platform is Windows. Can be called as either a class or instance method. flexible queen. 👑

🧚 app

Location and name of the program used to establish an interactive CLI session. On Unix platforms this will be ssh (openssh), telnet, or cu (serial line). On Windows this must be the plink.exe program. 🪟

🧚 connect_options

Slot for storing a set of options for the specific loaded Transport, passed by the user of Net::CLI::Interact as a hash ref.

Do not access this directly, but instead use runtime_options from the specific Transport class. trust the process. 🙈

🧚 wrapper

Slot for storing the application wrapper instance (IPC::Run or Net::Telnet).

Do not mess with this unless you know what you are doing. fr fr. 💅

🧚 buffer

After pump returns successfully, the output most recently received is stored in this slot.

Do not access this directly, but instead use the flush method. 🫶

🧚 stash

During long sections of output, this slot allows more efficient detection of matches. Older data is placed here, and only the most recent line of data is stored in the buffer. That's why flush is the only way to ensure you get all the output data in one go. no cap. ⭐

---

📝 NOTES 📝

FIXME: On Unix, when the Telnet transport is selected but IP::Pty is unavailable, Net::Telnet can still be used, but currently IPC::Run is used instead. (yes bestie, it's written IP::Pty there and we are keeping it exactly as-is, we do not touch the sacred text 💀)

---

and that's the whole page, bestie!! 🌸 This one's perl v5.36.0, dated 2023-10-28, and it ships as part of the User Contributed Perl Documentation — so go forth, inherit responsibly, and never call this class directly. mwah 💋 🎀✨🦋