|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.|
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.
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.
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( CW$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( CW$name )Returns true if a prompt of the given $name exists in the loaded phrasebooks.
Returns a list of the names of the current loaded Prompts.
macro( CW$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( CW$name )Returns true if a macro of the given $name exists in the loaded phrasebooks.
Returns a list of the names of the current loaded Macros.
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.
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 its the same as the current Prompt.
Format Interpolation Each send statement is in fact run through Perls sprintf command, so variables may be interpolated into the statement using standard "%" fields. For example:
macro show_int_x send show interface %s
Named Match References If youre 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 its 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 "%").
Oliver Gorwits <email@example.com>
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.
|perl v5.20.3||NET::CLI::INTERACT::PHRASEBOOK (3)||2015-01-06|