.\" 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::Role::Prompt 3pm"
.TH Net::CLI::Interact::Role::Prompt 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::Role::Prompt \- Command\-line prompt management
.SH "VERSION"
.IX Header "VERSION"
version 2.142720
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is another core component of Net::CLI::Interact, and its role is to
keep track of the current prompt on the connected command line interface. The
idea is that most \s-1CLI\s0 have a prompt where you issue commands, and are returned
some output which this module gathers. The prompt is a demarcation between
each command and its response data.
.PP
Note that although we \*(L"keep track\*(R" of the prompt, Net::CLI::Interact is not a
state machine, and the choice of command issued to the connected device bears
no relation to the current (or last matched) prompt.
.SH "INTERFACE"
.IX Header "INTERFACE"
.ie n .SS "set_prompt( $prompt_name )"
.el .SS "set_prompt( \f(CW$prompt_name\fP )"
.IX Subsection "set_prompt( $prompt_name )"
This method will be used most commonly by applications to select and set a
prompt from the Phrasebook which matches the current context of the connected
\&\s-1CLI\s0 session. This allows a sequence of commands to be sent which share the
same Prompt.
.PP
The name you pass in is looked up in the loaded Phrasebook and the entry's
regular expression stored internally. An exception is thrown if the named
Prompt is not known.
.PP
Typically you would either refer to a Prompt in a Macro, or set the prompt you
are expecting once for a sequence of commands in a particular \s-1CLI\s0 context.
.PP
When a Macro completes and it has been defined in the Phrasebook with an
explicit named Prompt at the end, we can assume the user is indicating some
change of context. Therefore the \f(CW\*(C`prompt\*(C'\fR is \fIautomatically updated\fR on such
occasions to have the regular expression from that named Prompt.
.SS "prompt_re"
.IX Subsection "prompt_re"
Returns the current Prompt in the form of a regular expression reference. The
Prompt is used as a default to catch the end of command response output, when
a Macro has not been set up with explicit Prompt matching.
.PP
Typically you would either refer to a Prompt in a Macro, or set the prompt you
are expecting once for a sequence of commands in a particular \s-1CLI\s0 context.
.SS "unset_prompt"
.IX Subsection "unset_prompt"
Use this method to empty the current \f(CW\*(C`prompt\*(C'\fR setting (see above). The effect
is that the module will automatically set the Prompt for itself based on the
last line of output received from the connected \s-1CLI.\s0 Do not use this option
unless you know what you are doing.
.SS "has_set_prompt"
.IX Subsection "has_set_prompt"
Returns True if there is currently a Prompt set, otherwise returns False.
.ie n .SS "prompt_looks_like( $name )"
.el .SS "prompt_looks_like( \f(CW$name\fP )"
.IX Subsection "prompt_looks_like( $name )"
Returns True if the current prompt matches the given named prompt. This is
useful when you wish to make a more specific check on the current prompt.
.ie n .SS "find_prompt( $wake_up? )"
.el .SS "find_prompt( \f(CW$wake_up\fP? )"
.IX Subsection "find_prompt( $wake_up? )"
A helper method that consumes output from the connected \s-1CLI\s0 session until a
line matches any one of the named Prompts in the loaded Phrasebook, at which
point no more output is consumed. As a consequence the \f(CW\*(C`prompt\*(C'\fR will be set
(see above).
.PP
This might be used when you're connecting to a device which maintains \s-1CLI\s0
state between session disconnects (for example a serial console), and you need
to discover the current state. However, \f(CW\*(C`find_prompt\*(C'\fR is executed
automatically for you if you call a \f(CW\*(C`cmd\*(C'\fR or \f(CW\*(C`macro\*(C'\fR before any interaction
with the \s-1CLI.\s0
.PP
The current device output will be scanned against all known named Prompts. If
nothing is found, the default behaviour is to die. Passing a positive number
to the method (as \f(CW$wake_up\fR) will instead send the content of our
\&\f(CW\*(C`wake_up_msg\*(C'\fR slot (see below), typically a carriage return, and try to match
again. The idea is that by sending one carriage return, the connected device
will print its \s-1CLI\s0 prompt. This \*(L"send and try to match\*(R" process will be
repeated up to "\f(CW$wake_up\fR" times.
.SS "wake_up_msg"
.IX Subsection "wake_up_msg"
Text sent to a device within the \f(CW\*(C`find_prompt\*(C'\fR method if no output has so far
matched any known named Prompt. Default is the value of the \fIoutput record
separator\fR from the Transport (one newline).
.SS "last_prompt"
.IX Subsection "last_prompt"
Returns the Prompt which most recently was matched and terminated gathering of
output from the connected \s-1CLI.\s0 This is a simple text string.
.SS "last_prompt_re"
.IX Subsection "last_prompt_re"
Returns the text which was most recently matched and terminated gathering of
output from the connected \s-1CLI,\s0 as a quote-escaped regular expression with line
start and end anchors.
.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.