NAME¶
Net::CLI::Interact::Phrasebook - Load command phrasebooks from a Library
VERSION¶
version 2.142720
DESCRIPTION¶
A command phrasebook is where you store the repeatable sequences of commands
which can be sent to connected network devices. An example would be a command
to show the configuration of a device: storing this in a phrasebook (sometimes
known as a dictionary) saves time and effort.
This module implements the loading and preparing of phrasebooks from an on-disk
file-based hierarchical library, and makes them available to the application
as smart objects for use in Net::CLI::Interact sessions. Entries in the
phrasebook will be one of the following types:
- Prompt
- Named regular expressions that match the content of a single line of text
in the output returned from a connected device. They are a demarcation
between commands sent and responses returned.
- Macro
- Alternating sequences of command statements sent to the device, and
regular expressions to match the response. There are different kinds of
Macro, explained below.
The named regular expressions used in Prompts and Macros are known as
Match statements. The command statements in Macros which are sent to
the device are known as
Send statements. That is, Prompts and Macros
are built from one or more Match and Send statements.
Each Send or Match statement becomes an instance of the
Net::CLI::Interact::Action class. These are built up into Prompts and Macros,
which become instances of the Net::CLI::Interact::ActionSet class.
USAGE¶
A phrasebook is a plain text file containing named Prompts or Macros. Each file
exists in a directory hierarchy, such that files "deeper" in the
hierarchy have their entries override the similarly named entries higher up.
For example:
/dir1/file1
/dir1/file2
/dir1/dir2/file3
Entries in "file3" sharing a name with any entries from
"file1" or "file2" will take precedence. Those in
"file2" will also override entries in "file1", because
asciibetical sorting places the files in that order, and later definitions
with the same name and type override earlier ones.
When this module is loaded, a
personality key is required. This locates a
directory on disk, and then the files in that directory and all its ancestors
in the hierarchy are loaded. The directories to search are specified by two
Library options (see below). All phrasebooks matching the given
personality are loaded, allowing a user to override or augment the
default, shipped phrasebooks.
INTERFACE¶
new( \%options )¶
This takes the following options, and returns a loaded phrasebook object:
- "personality => $directory" (required)
- The name of a directory component on disk. Any files higher in the
libraries hierarchy are also loaded, but entries in files contained within
this directory, or "closer" to it, will take precedence.
- "library => $directory | \@directories"
- First library hierarchy, specified either as a single directory or a list
of directories that are searched in order. The idea is that this option be
set in your application code, perhaps specifying some directory of
phrasebooks shipped with the distribution.
- "add_library => $directory | \@directories"
- Second library hierarchy, specified either as a single directory or a list
of directories that are searched in order. This parameter is for the
end-user to provide the location(s) of their own phrasebook(s). Any
entries found via this path will override those found via the first
"library" path.
prompt( $name )¶
Returns the Prompt associated to the given $name, or throws an exception if no
such prompt can be found. The returned object is an instance of
Net::CLI::Interact::ActionSet.
has_prompt( $name )¶
Returns true if a prompt of the given $name exists in the loaded phrasebooks.
prompt_names¶
Returns a list of the names of the current loaded Prompts.
macro( $name )¶
Returns the Macro associated to the given $name, or throws an exception if no
such macro can be found. The returned object is an instance of
Net::CLI::Interact::ActionSet.
has_macro( $name )¶
Returns true if a macro of the given $name exists in the loaded phrasebooks.
macro_names¶
Returns a list of the names of the current loaded Macros.
Prompt¶
A Prompt is a named regular expression which matches the content of a single
line of text. Here is an example:
prompt configure
match /\(config[^)]*\)# ?$/
On the first line is the keyword "prompt" followed by the name of the
Prompt, which must be a valid Perl identifier (letters, numbers, underscores
only).
On the immediately following line is the keyword "match" followed by a
regular expression, enclosed in two forward-slash characters. Currently, no
alternate bookend characters are supported, nor are regular expression
modifiers (such as "xism") outside of the match, but you can of
course include them within.
The Prompt is used to find out when the connected CLI has emitted all of the
response to a command. Try to make the Prompt as specific as possible,
including line-end anchors. Remember that it will be matched against one line
of text, only.
Macro¶
In general, Macros are alternating sequences of commands to send to the
connected CLI, and regular expressions to match the end of the returned
response. Macros are useful for issueing commands which have intermediate
prompts, or confirmation steps. They also support the
slurping of
additional output when the connected CLI has split the response into pages.
At its simplest a Macro can be just one command:
macro show_int_br
send show ip int br
match /> ?$/
On the first line is the keyword "macro" followed by the name of the
Macro, which must be a valid Perl identifier (letters, numbers, underscores
only).
On the immediately following line is the keyword "send" followed by a
space and then any text up until the end of the line, and if you want to
include whitespace at the beginning or end of the command, use quotes. This
text is sent to the connected CLI as a single command statement. The next line
contains the keyword "match" followed by the Prompt (regular
expression) which will terminate gathering of returned output from the sent
command.
Macros support the following features:
- Automatic Matching
- Normally, you ought always to specify "send" statements along
with a following "match" statement so that the module can tell
when the output from your command has ended. However you can omit any
Match and the module will insert either the current "prompt"
value if set by the user, or the last Prompt from the last Macro. So the
previous example could be re-written as:
macro show_int_br
send show ip int br
You can have as many "send" statements as you like, and the Match
statements will be inserted for you:
macro show_int_br_and_timestamp
send show ip int br
send show clock
However it is recommended that this type of sequence be implemented as
individual commands (or separate Macros) rather than a single Macro, as it
will be easier for you to retrieve the command response(s). Normally the
Automatic Matching is used just to allow missing off of the final Match
statement when it's the same as the current Prompt.
- Format Interpolation
- Each "send" statement is in fact run through Perl's
"sprintf" command, so variables may be interpolated into the
statement using standard "%" fields. For example:
macro show_int_x
send show interface %s
The method for passing variables into the module upon execution of this
Macro is documented in Net::CLI::Interact::Role::Engine. This feature is
useful for username/password prompts.
- Named Match References
- If you're going to use the same Match (regular expression) in a number of
Macros, then set it up as a Prompt (see above) and refer to it by name,
instead:
prompt priv_exec
match /# ?$/
macro to_priv_exec
send enable
match /[Pp]assword: ?$/
send %s
match priv_exec
As you can see, in the case of the last Match, we have the keyword
"match" followed by the name of a defined Prompt. To match
multiple defined Prompts use this syntax (with as many named references as
you like):
macro to_privileged
send enable
match username_prompt or priv_exec
- Continuations
- Sometimes the connected CLI will not know it's talking to a program and so
paginate the output (that is, split it into pages). There is usually a
keypress required between each page. This is supported via the following
syntax:
macro show_run
send show running-config
follow / --More-- / with ' '
On the line following the "send" statement is the keyword
"follow" and a regular expression enclosed in forward-slashes.
This is the Match which will, if seen in the command output, trigger the
continuation. On the line you then have the keyword "with"
followed by a space and some text, until the end of the line. If you need
to enclose whitespace use quotes, as in the example.
The module will send the continuation text and gobble the matched prompt
from the emitted output so you only have one complete piece of text
returned, even if split over many pages. The sent text can contain
metacharacters such as "\n" for a newline.
Note that in the above example the "follow" statement should be
seen as an extension of the "send" statement. There is still an
implicit Match prompt added at the end of this Macro, as per Automatic
Matching, above.
- Line Endings
- Normally all sent command statements are appended with a newline (or the
value of "ors", if set). To suppress that feature, use the
keyword "put" instead of "send". However this does not
prevent the Format Interpolation via "sprintf" as described
above (simply use "%%" to get a literal "%").
AUTHOR¶
Oliver Gorwits <oliver@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by Oliver Gorwits.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.