.\" 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::Role::Engine 3pm"
.TH Net::CLI::Interact::Role::Engine 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::Role::Engine \- Statement execution engine
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is the core of Net::CLI::Interact, and serves to take entries
from your loaded Phrasebooks, issue them to
connected devices, and gather the returned output.
.SH "INTERFACE"
.IX Header "INTERFACE"
.ie n .SS "cmd( $command_statement, \e%options? )"
.el .SS "cmd( \f(CW$command_statement\fP, \e%options? )"
.IX Subsection "cmd( $command_statement, %options? )"
Execute a single command statement on the connected device, and consume output
until there is a match with the current \fIprompt\fR. The statement is executed
verbatim on the device, with a newline appended.
.PP
The following options are supported:
.ie n .IP """timeout => $seconds"" (optional)" 4
.el .IP "\f(CWtimeout => $seconds\fR (optional)" 4
.IX Item "timeout => $seconds (optional)"
Sets a value of \f(CW\*(C`timeout\*(C'\fR for the
Transport local to this call of \f(CW\*(C`cmd\*(C'\fR, that
overrides whatever is set in the Transport, or the default of 10 seconds.
.ie n .IP """no_ors => 1"" (optional)" 4
.el .IP "\f(CWno_ors => 1\fR (optional)" 4
.IX Item "no_ors => 1 (optional)"
When passed a true value, a newline character (in fact the value of \f(CW\*(C`ors\*(C'\fR)
will not be appended to the statement sent to the device.
.ie n .IP """match => $name | $regexpref | \e@names_and_regexprefs"" (optional)" 4
.el .IP "\f(CWmatch => $name | $regexpref | \e@names_and_regexprefs\fR (optional)" 4
.IX Item "match => $name | $regexpref | @names_and_regexprefs (optional)"
Allows this command (only) to complete with a custom match, which must be one
or more of either the name of a loaded phrasebook Prompt or your own regular
expression reference (\f(CW\*(C`qr//\*(C'\fR). The module updates the current prompt to
be the same value on a successful match.
.PP
In scalar context the \f(CW\*(C`last_response\*(C'\fR is returned (see below). In list
context the gathered response is returned as a list of lines. In both cases
your local platform's newline character will end all lines.
.ie n .SS "macro( $macro_name, \e%options? )"
.el .SS "macro( \f(CW$macro_name\fP, \e%options? )"
.IX Subsection "macro( $macro_name, %options? )"
Execute the commands contained within the named Macro, which must be loaded
from a Phrasebook. Options to control the output, including variables for
substitution into the Macro, are passed in the \f(CW%options\fR hash reference.
.PP
The following options are supported:
.ie n .IP """params => \e@values"" (optional)" 4
.el .IP "\f(CWparams => \e@values\fR (optional)" 4
.IX Item "params => @values (optional)"
If the Macro contains commands using \f(CW\*(C`sprintf\*(C'\fR Format variables then the
corresponding parameters must be passed in this value as an array reference.
.Sp
Values are consumed from the provided array reference and passed to the
\&\f(CW\*(C`send\*(C'\fR commands in the Macro in order, as needed. An exception will be thrown
if there are insufficient parameters.
.ie n .IP """timeout => $seconds"" (optional)" 4
.el .IP "\f(CWtimeout => $seconds\fR (optional)" 4
.IX Item "timeout => $seconds (optional)"
Sets a value of \f(CW\*(C`timeout\*(C'\fR for the
Transport local to this call of \f(CW\*(C`macro\*(C'\fR,
that overrides whatever is set in the Transport, or the default of 10 seconds.
.PP
An exception will be thrown if the Match statements in the Macro are not
successful against the output returned from the device. This is based on the
value of \f(CW\*(C`timeout\*(C'\fR, which controls how long the module waits for matching
output.
.PP
In scalar context the \f(CW\*(C`last_response\*(C'\fR is returned (see below). In list
context the gathered response is returned as a list of lines. In both cases
your local platform's newline character will end all lines.
.SS "last_response"
.IX Subsection "last_response"
Returns the gathered output after issuing the last recent \f(CW\*(C`send\*(C'\fR command
within the most recent \f(CW\*(C`cmd\*(C'\fR or \f(CW\*(C`prompt\*(C'\fR. That is, you get the output from
the last command sent to the connected device.
.PP
In scalar context all data is returned. In list context the gathered response
is returned as a list of lines. In both cases your local platform's newline
character will end all lines.
.SS "last_actionset"
.IX Subsection "last_actionset"
Returns the complete ActionSet that was
constructed from the most recent \f(CW\*(C`macro\*(C'\fR or \f(CW\*(C`cmd\*(C'\fR execution. This will be a
sequence of Actions that correspond to \f(CW\*(C`send\*(C'\fR
and \f(CW\*(C`match\*(C'\fR statements.
.PP
In the case of a Macro these directly relate to the contents of your
Phrasebook, with the possible addition of \f(CW\*(C`match\*(C'\fR statements added
automatically. In the case of a \f(CW\*(C`cmd\*(C'\fR execution, an \*(L"anonymous\*(R" Macro is
constructed which consists of a single \f(CW\*(C`send\*(C'\fR and a single \f(CW\*(C`match\*(C'\fR.
.SH "COMPOSITION"
.IX Header "COMPOSITION"
See the following for further interface details:
.IP "\(bu" 4
Net::CLI::Interact::Role::Prompt