.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::CLI::Interact::Transport::Base 3pm"
.TH Net::CLI::Interact::Transport::Base 3pm "2017-11-08" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::CLI::Interact::Transport::Base \- Spawns an Interactive CLI Session
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a generic cross-platform \s-1API\s0 with the purpose of
interacting with a command line interface.
.PP
On Windows the IPC::Run module is used and on Unix when IO::Pty is
available (it requires a compiler) Net::Telnet, else \f(CW\*(C`IPC::Run\*(C'\fR. In all
cases, a program such as openssh is started and methods provided to send and
receive data from the interactive session.
.PP
You should not use this class directly, but instead inherit from it in
specific Transport that will set the application command line name, and
marshall any runtime options. The \s-1OS\s0 platform is detected automatically.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "init"
.IX Subsection "init"
This method \fImust\fR be called before any other, to bootstrap the application
wrapper module (IPC::Run or Net::Telnet). However, via Net::CLI::Interact's
\&\f(CW\*(C`cmd\*(C'\fR, \f(CW\*(C`match\*(C'\fR or \f(CW\*(C`find_prompt\*(C'\fR it will be called for you automatically.
.PP
Two attributes of the specific loaded Transport are used. First the
Application set in \f(CW\*(C`app\*(C'\fR is of course required, plus the options in the
Transport's \f(CW\*(C`runtime_options\*(C'\fR are retrieved, if set, and passed as command
line arguments to the Application.
.SS "connect_ready"
.IX Subsection "connect_ready"
Returns True if \f(CW\*(C`connect\*(C'\fR has been called successfully, otherwise returns
False.
.SS "disconnect"
.IX Subsection "disconnect"
Undefines the application wrapper flushes any output data buffer such that
the next call to \f(CW\*(C`cmd\*(C'\fR or \f(CW\*(C`macro\*(C'\fR will cause a new connection to be made.
Useful if you intentionally timeout a command and end up with junk in the
output buffer.
.SS "do_action"
.IX Subsection "do_action"
When passed a Net::CLI::Interact::Action instance, will execute the
contained instruction on the connected \s-1CLI.\s0 This might be a command to
\&\f(CW\*(C`send\*(C'\fR, or a regular expression to \f(CW\*(C`match\*(C'\fR in the output.
.PP
Features of the commands and prompts are supported, such as Continuation
matching (and slurping), and sending without an \fIoutput record separator\fR.
.PP
On failing to succeed with a Match, the module will time-out (see \f(CW\*(C`timeout\*(C'\fR,
below) and raise an exception.
.PP
Output returned after issuing a command is stored within the Match Action's
\&\f(CW\*(C`response\*(C'\fR and \f(CW\*(C`response_stash\*(C'\fR slots by this method, with the latter then
marshalled into the correct \f(CW\*(C`send\*(C'\fR Action by the
ActionSet.
.ie n .SS "put( @data )"
.el .SS "put( \f(CW@data\fP )"
.IX Subsection "put( @data )"
Items in \f(CW@data\fR are joined together by an empty string and sent as input to
the connected program's interactive session.
.SS "pump"
.IX Subsection "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 \f(CW\*(C`buffer\*(C'\fR and \f(CW\*(C`timeout\*(C'\fR.
.SS "flush"
.IX Subsection "flush"
Empties the buffer used for response data returned from the connected \s-1CLI,\s0 and
returns that data as a single text string (possibly with embedded newlines).
.ie n .SS "timeout( $seconds? )"
.el .SS "timeout( \f(CW$seconds\fP? )"
.IX Subsection "timeout( $seconds? )"
When \f(CW\*(C`do_action\*(C'\fR 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.
.PP
The number of seconds to wait is set via this method, which will also return
the current value of \f(CW\*(C`timeout\*(C'\fR. The default value is 10 seconds.
.SS "irs_re"
.IX Subsection "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 \f(CW\*(C`ors\*(C'\fR value (by default a newline character). The \f(CW\*(C`irs_re\*(C'\fR
is used internally by the module and is:
.PP
.Vb 1
\& qr/(?:\e015\e012|\e015|\e012)/  # i.e. CRLF or CR or LF
.Ve
.SS "ors"
.IX Subsection "ors"
Line separator character(s) appended to a command sent to the connected \s-1CLI.\s0
This defaults to a newline on the application's platform.
.SS "logger"
.IX Subsection "logger"
Slot for storing a reference to the application's
Logger object.
.SS "is_win32"
.IX Subsection "is_win32"
Returns true if the current platform is Windows. Can be called as either a
class or instance method.
.SS "app"
.IX Subsection "app"
Location and name of the program used to establish an interactive \s-1CLI\s0 session.
On Unix platforms this will be \f(CW\*(C`ssh\*(C'\fR (openssh), \f(CW\*(C`telnet\*(C'\fR, or \f(CW\*(C`cu\*(C'\fR (serial
line). On Windows this must be the \f(CW\*(C`plink.exe\*(C'\fR program.
.SS "connect_options"
.IX Subsection "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 \f(CW\*(C`runtime_options\*(C'\fR from the specific Transport class.
.SS "wrapper"
.IX Subsection "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.
.SS "buffer"
.IX Subsection "buffer"
After \f(CW\*(C`pump\*(C'\fR returns successfully, the output most recently received is
stored in this slot. Do not access this directly, but instead use the \f(CW\*(C`flush\*(C'\fR
method.
.SS "stash"
.IX Subsection "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 \f(CW\*(C`buffer\*(C'\fR. That's why \f(CW\*(C`flush\*(C'\fR is the only way to ensure you get
all the output data in one go.
.SH "NOTES"
.IX Header "NOTES"
\&\fB\s-1FIXME\s0\fR: On Unix, when the Telnet transport is selected but \f(CW\*(C`IP::Pty\*(C'\fR is
unavailable, \f(CW\*(C`Net::Telnet\*(C'\fR can still be used, but currently \f(CW\*(C`IPC::Run\*(C'\fR is
used instead.