.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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::Manual::Cookbook 3pm"
.TH Net::CLI::Interact::Manual::Cookbook 3pm "2012-06-12" "perl v5.14.2" "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::Manual::Cookbook \- Miscellaneous recipes
.SH "Windows Support"
.IX Header "Windows Support"
The library works just fine under native windows (i.e use something like
Strawberry Perl \- no need for cygwin), for Telnet, Serial and \s-1SSH\s0 connections.
However one additional step is required for you to have success:
.PP
You \fBmust\fR download the \f(CW\*(C`plink.exe\*(C'\fR application, and pass its filesystem
location in the \f(CW\*(C`app\*(C'\fR parameter to \f(CW\*(C`new()\*(C'\fR. Do not try to use any other
Telnet or \s-1SSH\s0 programs (for instance the Windows bundled \f(CW\*(C`telnet\*(C'\fR) \- they
\&\fIwill not work\fR. Here's an example:
.PP
.Vb 6
\& my $s = Net::CLI::Interact\->new(
\&     personality => "cisco",
\&     transport => "Telnet",
\&     (Net::CLI::Interact::Transport::is_win32() ?
\&         (app => "$ENV{HOMEPATH}\e\eDesktop\e\eplink.exe") : () ),
\& );
.Ve
.SH "Unix Support"
.IX Header "Unix Support"
The library works fine on most Unix platforms. It will try to use the native
\&\f(CW\*(C`telnet\*(C'\fR, \f(CW\*(C`ssh\*(C'\fR (openssh) and \f(CW\*(C`cu\*(C'\fR programs for Telnet, \s-1SSH\s0 and Serial
connections, respectively. If you want to use another application, pass it in
the \f(CW\*(C`app\*(C'\fR parameter to \f(CW\*(C`new\*(C'\fR.
.PP
In some Unix environments there can be zombie child processes left around
after running your script. If this happens, set the \f(CW\*(C`reap\*(C'\fR option, like so:
.PP
.Vb 7
\& my $s = Net::CLI::Interact\->new(
\&     personality => "cisco",
\&     transport => "Telnet",
\&     connect_options => {
\&        reap => 1,
\&    },
\& );
.Ve
.SH "Phrasebook Entries"
.IX Header "Phrasebook Entries"
.SS "Prompts"
.IX Subsection "Prompts"
These are nothing more than named regular expressions:
.PP
.Vb 2
\& prompt configure
\&     match /\e(config[^)]*\e)# ?$/
.Ve
.SS "Macros"
.IX Subsection "Macros"
This example waits for the device to ask \*(L"[startup\-config]?\*(R" and then responds
with the text \f(CW\*(C`startup\-config\*(C'\fR.
.PP
.Vb 4
\& macro copy_run_start
\&     send copy running\-config startup\-config
\&     match /Destination filename \e[startup\-config\e]\e?$/
\&     send startup\-config
.Ve
.PP
To send instead a press of the Return key (\fIoutput record separator\fR), use:
.PP
.Vb 4
\& macro write_mem
\&     send copy running\-config startup\-config
\&     match /Destination filename \e[startup\-config\e]\e?$/
\&     send \*(Aq\*(Aq
.Ve
.PP
To instead allow the user to pass in the file name, use a \f(CW\*(C`sprintf\*(C'\fR format.
.PP
.Vb 4
\& macro save_to_file
\&     send copy running\-config startup\-config
\&     match /Destination filename \e[startup\-config\e]\e?$/
\&     send %s
.Ve
.PP
The user \fImust\fR then pass a parameter to the \f(CW\*(C`macro\*(C'\fR call, even if it's an
empty string:
.PP
.Vb 3
\& $s\->macro(\*(Aqsave_to_file\*(Aq, { params => [\*(Aqfile_name\*(Aq] });
\& # or
\& $s\->macro(\*(Aqsave_to_file\*(Aq, { params => [\*(Aq\*(Aq] });
.Ve
.SS "Continuations"
.IX Subsection "Continuations"
These are Macros which start with a match instead of a send:
.PP
.Vb 3
\& macro more_pages
\&     match / \-\-More\-\- /
\&     send \*(Aq \*(Aq
.Ve
.PP
Note that the parameter of the \f(CW\*(C`send\*(C'\fR is \fInot\fR sent with a Return character
(\fIoutput record separator\fR) appended.
.PP
When included in a macro, the continuation can be in-line, like this:
.PP
.Vb 3
\& macro show_ip_route
\&     send show ip route
\&     follow / \-\-More\-\- / with \*(Aq \*(Aq
.Ve
.SH "Running Commands"
.IX Header "Running Commands"
.SS "Standalone Commands"
.IX Subsection "Standalone Commands"
Simply send the command you wish to execute to the library. If not already
done, a connection to the device will be established automatically:
.PP
.Vb 1
\& $s\->cmd(\*(Aqshow ip int br\*(Aq);
.Ve
.PP
Normally this matches against a default prompt, which has been discovered
automatically, or set by you:
.PP
.Vb 1
\& $s\->set_prompt(\*(Aquser_prompt\*(Aq);
.Ve
.PP
It's also possible to pass in a custom prompt for this command only:
.PP
.Vb 1
\& $s\->cmd(\*(Aqshow ip int br\*(Aq, { match => qr/special prompt>$/ });
.Ve
.SS "Composite Macro Commands"
.IX Subsection "Composite Macro Commands"
Call a predefined Macro from the phrasebook using this method:
.PP
.Vb 1
\& $s\->macro(\*(Aqwrite_mem\*(Aq);
.Ve
.PP
Sometimes the Macro needs parameters:
.PP
.Vb 1
\& $s\->macro(\*(Aqto_priv_exec\*(Aq, { params => [\*(Aqmy_password\*(Aq] });
.Ve
.PP
You can't really create a Macro on the fly very easily, but with suitable use
of \f(CW\*(C`cmd()\*(C'\fR, \f(CW\*(C`set_prompt()\*(C'\fR, and the \f(CW\*(C`match\*(C'\fR option to \f(CW\*(C`cmd()\*(C'\fR it's
possible to achieve some simple flexibility.
.SH "Reconfiguring On-the-Fly"
.IX Header "Reconfiguring On-the-Fly"
.SS "Phrasebook"
.IX Subsection "Phrasebook"
It's possible to load a new phrasebook by the following method, which must be
passed at least the name of the personality:
.PP
.Vb 1
\& $s\->set_phrasebook({ personality => \*(Aqios\*(Aq });
.Ve
.PP
You can pass any options which the
Phrasebook module itself would take.
.SS "Prompt"
.IX Subsection "Prompt"
The current prompt can be changed by passing the name of the new Prompt as it
is known by the phrasebook:
.PP
.Vb 1
\& $s\->set_prompt(\*(Aqname\*(Aq);
.Ve
.PP
If you want to test whether the current prompt matches a diffrent named Prompt
from the phrasebook, this method can be used:
.PP
.Vb 1
\& $s\->prompt_looks_like(\*(Aqname\*(Aq);
.Ve