.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 3pm"
.TH Net::CLI::Interact 3pm "2014-09-29" "perl v5.20.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 \- Toolkit for CLI Automation
.SH "VERSION"
.IX Header "VERSION"
version 2.142720
.SH "PURPOSE"
.IX Header "PURPOSE"
This module exists to support developers of applications and libraries which
must interact with a command line interface.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Net::CLI::Interact;
\& 
\& my $s = Net::CLI::Interact\->new({
\&    personality => \*(Aqcisco\*(Aq,
\&    transport   => \*(AqTelnet\*(Aq,
\&    connect_options => { host => \*(Aq192.0.2.1\*(Aq },
\& });
\& 
\& # respond to a usename/password prompt
\& $s\->macro(\*(Aqto_user_exec\*(Aq, {
\&     params => [\*(Aqmy_username\*(Aq, \*(Aqmy_password\*(Aq],
\& });
\& 
\& my $interfaces = $s\->cmd(\*(Aqshow ip interfaces brief\*(Aq);
\& 
\& $s\->macro(\*(Aqto_priv_exec\*(Aq, {
\&     params => [\*(Aqmy_password\*(Aq],
\& });
\& # matched prompt is updated automatically
\& 
\& # paged output is slurped into one response
\& $s\->macro(\*(Aqshow_run\*(Aq);
\& my $config = $s\->last_response;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Automating command line interface (\s-1CLI\s0) interactions is not a new idea, but
can be tricky to implement. This module aims to provide a simple and
manageable interface to \s-1CLI\s0 interactions, supporting:
.IP "\(bu" 4
\&\s-1SSH,\s0 Telnet and Serial-Line connections
.IP "\(bu" 4
Unix and Windows support
.IP "\(bu" 4
Reuseable device command phrasebooks
.PP
If you're a new user, please read the
Tutorial. There's also a
Cookbook and a Phrasebook
Listing. For a more complete worked
example check out the Net::Appliance::Session distribution, for which this
module was written.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "new( \e%options )"
.IX Subsection "new( %options )"
Prepares a new session for you, but will not connect to any device. On
Windows platforms, you \fBmust\fR download the \f(CW\*(C`plink.exe\*(C'\fR program, and pass
its location to the \f(CW\*(C`app\*(C'\fR parameter. Other options are:
.ie n .IP """personality => $name"" (required)" 4
.el .IP "\f(CWpersonality => $name\fR (required)" 4
.IX Item "personality => $name (required)"
The family of device command phrasebooks to load. There is a built-in library
within this module, or you can provide a search path to other libraries. See
Net::CLI::Interact::Manual::Phrasebook for further details.
.ie n .IP """transport => $backend"" (required)" 4
.el .IP "\f(CWtransport => $backend\fR (required)" 4
.IX Item "transport => $backend (required)"
The name of the transport backend used for the session, which may be one of
Telnet,
\&\s-1SSH\s0, or
Serial.
.ie n .IP """connect_options => \e%options""" 4
.el .IP "\f(CWconnect_options => \e%options\fR" 4
.IX Item "connect_options => %options"
If the transport backend can take any options (for example the target
hostname), then pass those options in this value as a hash ref. See the
respective manual pages for each transport backend for further details.
.ie n .IP """log_at => $log_level""" 4
.el .IP "\f(CWlog_at => $log_level\fR" 4
.IX Item "log_at => $log_level"
To make using the \f(CW\*(C`logger\*(C'\fR somewhat easier, you can pass this argument the
name of a log \fIlevel\fR (such as \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`info\*(C'\fR, etc) and all logging in the
library will be enabled at that level. Use \f(CW\*(C`debug\*(C'\fR to learn about how the
library is working internally. See Net::CLI::Interact::Logger for a list of
the valid level names.
.ie n .IP """timeout => $seconds""" 4
.el .IP "\f(CWtimeout => $seconds\fR" 4
.IX Item "timeout => $seconds"
Configures a default timeout value, in seconds, for interaction with the
remote device. The default is 10 seconds. You can also set timeout on a
per-command or per-macro call (see below).
.Sp
Note that this does not (currently) apply to the initial connection.
.ie n .SS "cmd( $command )"
.el .SS "cmd( \f(CW$command\fP )"
.IX Subsection "cmd( $command )"
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
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( $name, \e%options? )"
.el .SS "macro( \f(CW$name\fP, \e%options? )"
.IX Subsection "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
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 the most recent \f(CW\*(C`cmd\*(C'\fR or \f(CW\*(C`macro\*(C'\fR. 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 "transport"
.IX Subsection "transport"
Returns the Transport backend which was
loaded based on the \f(CW\*(C`transport\*(C'\fR option to \f(CW\*(C`new\*(C'\fR. See the
Telnet,
\&\s-1SSH\s0, or
Serial documentation for further
details.
.SS "phrasebook"
.IX Subsection "phrasebook"
Returns the Phrasebook object which was loaded based on the \f(CW\*(C`personality\*(C'\fR
option given to \f(CW\*(C`new\*(C'\fR. See Net::CLI::Interact::Phrasebook for further
details.
.SS "set_phrasebook( \e%options )"
.IX Subsection "set_phrasebook( %options )"
Allows you to (re\-)configure the loaded phrasebook, perhaps changing the
personality or library, or other properties. The \f(CW%options\fR Hash ref should
be any parameters from the Phrasebook
module, but at a minimum must include a \f(CW\*(C`personality\*(C'\fR.
.ie n .SS "set_default_contination( $macro_name )"
.el .SS "set_default_contination( \f(CW$macro_name\fP )"
.IX Subsection "set_default_contination( $macro_name )"
Briefly, a Continuation handles the slurping of paged output from commands.
See the Net::CLI::Interact::Phrasebook documentation for further details.
.PP
Pass in the name of a defined Contination (Macro) to enable paging handling as
a default for all sent commands. This is an alternative to describing the
Continuation format in each Macro.
.PP
To unset the default Continuation, call the \f(CW\*(C`clear_default_continuation\*(C'\fR
method.
.SS "logger"
.IX Subsection "logger"
This is the application's Logger object. A
powerful logging subsystem is available to your application, built upon the
Log::Dispatch distribution. You can enable logging of this module's
processes at various levels, or add your own logging statements.
.ie n .SS "set_global_log_at( $level )"
.el .SS "set_global_log_at( \f(CW$level\fP )"
.IX Subsection "set_global_log_at( $level )"
To make using the \f(CW\*(C`logger\*(C'\fR somewhat easier, you can pass this method the
name of a log \fIlevel\fR (such as \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`info\*(C'\fR, etc) and all logging in the
library will be enabled at that level. Use \f(CW\*(C`debug\*(C'\fR to learn about how the
library is working internally. See Net::CLI::Interact::Logger for a list of
the valid level names.
.SH "FUTHER READING"
.IX Header "FUTHER READING"
.SS "Prompt Matching"
.IX Subsection "Prompt Matching"
Whenever a command statement is issued, output is slurped until a matching
prompt is seen in that output. Control of the Prompts is shared between the
definitions in Net::CLI::Interact::Phrasebook dictionaries, and methods of
the Net::CLI::Interact::Role::Prompt core component. See that module's
documentation for further details.
.SS "Actions and ActionSets"
.IX Subsection "Actions and ActionSets"
All commands and macros are composed from their phrasebook definitions into
Actions and
ActionSets (iterable sequences of Actions).
See those modules' documentation for further details, in case you wish to
introspect their structures.
.SH "COMPOSITION"
.IX Header "COMPOSITION"
See the following for further interface details:
.IP "\(bu" 4
Net::CLI::Interact::Role::Engine
.SH "AUTHOR"
.IX Header "AUTHOR"
Oliver Gorwits <oliver@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Oliver Gorwits.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.