NAME

       Net::CLI::Interact::Phrasebook - Load command phrasebooks from a Library

VERSION

       version 2.133420

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.

PHRASEBOOK FORMAT

   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) 2013 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.