Filewatcher File Search File Search
Catalog
Content Search
» » » » » libnet-cli-interact-perl_1.121640-1_all.deb » Content »
pkg://libnet-cli-interact-perl_1.121640-1_all.deb:95100/usr/share/man/man3/  info  control  downloads

libnet-cli-interact-perl - toolkit for CLI Automation…  more info»

Net::CLI::Interact::Phrasebook.3pm.gz

Net::CLI::InteracUserhContributedNet::CLI::Interact::Phrasebook(3pm)



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

VERSION
       version 1.121640

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 directory root is specified by two Library options.

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) 2012 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.14.2                 2012Net::CLI::Interact::Phrasebook(3pm)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com