1Net::CLI::Interact::PhrUasseerboCookn(t3r)ibuted Perl DoNceutm:e:nCtLaIt:i:oInnteract::Phrasebook(3)
2
3
4

NAME

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

DESCRIPTION

10       A command phrasebook is where you store the repeatable sequences of
11       commands which can be sent to connected network devices. An example
12       would be a command to show the configuration of a device: storing this
13       in a phrasebook (sometimes known as a dictionary) saves time and
14       effort.
15
16       This module implements the loading and preparing of phrasebooks from an
17       on-disk file-based hierarchical library, and makes them available to
18       the application as smart objects for use in Net::CLI::Interact
19       sessions.  Entries in the phrasebook will be one of the following
20       types:
21
22       Prompt
23           Named regular expressions that match the content of a single line
24           of text in the output returned from a connected device. They are a
25           demarcation between commands sent and responses returned.
26
27       Macro
28           Alternating sequences of command statements sent to the device, and
29           regular expressions to match the response. There are different
30           kinds of Macro, explained below.
31
32       The named regular expressions used in Prompts and Macros are known as
33       Match statements. The command statements in Macros which are sent to
34       the device are known as Send statements. That is, Prompts and Macros
35       are built from one or more Match and Send statements.
36
37       Each Send or Match statement becomes an instance of the
38       Net::CLI::Interact::Action class. These are built up into Prompts and
39       Macros, which become instances of the Net::CLI::Interact::ActionSet
40       class.
41

USAGE

43       A phrasebook is a plain text file containing named Prompts or Macros.
44       Each file exists in a directory hierarchy, such that files "deeper" in
45       the hierarchy have their entries override the similarly named entries
46       higher up.  For example:
47
48        /dir1/file1
49        /dir1/file2
50        /dir1/dir2/file3
51
52       Entries in "file3" sharing a name with any entries from "file1" or
53       "file2" will take precedence. Those in "file2" will also override
54       entries in "file1", because asciibetical sorting places the files in
55       that order, and later definitions with the same name and type override
56       earlier ones.
57
58       When this module is loaded, a personality key is required. This locates
59       a directory on disk, and then the files in that directory and all its
60       ancestors in the hierarchy are loaded. The directories to search are
61       specified by two Library options (see below). All phrasebooks matching
62       the given personality are loaded, allowing a user to override or
63       augment the default, shipped phrasebooks.
64

INTERFACE

66   new( \%options )
67       This takes the following options, and returns a loaded phrasebook
68       object:
69
70       "personality => $directory" (required)
71           The name of a directory component on disk. Any files higher in the
72           libraries hierarchy are also loaded, but entries in files contained
73           within this directory, or "closer" to it, will take precedence.
74
75       "library => $directory | \@directories"
76           First library hierarchy, specified either as a single directory or
77           a list of directories that are searched in order. The idea is that
78           this option be set in your application code, perhaps specifying
79           some directory of phrasebooks shipped with the distribution.
80
81       "add_library => $directory | \@directories"
82           Second library hierarchy, specified either as a single directory or
83           a list of directories that are searched in order. This parameter is
84           for the end-user to provide the location(s) of their own
85           phrasebook(s). Any entries found via this path will override those
86           found via the first "library" path.
87
88   prompt( $name )
89       Returns the Prompt associated to the given $name, or throws an
90       exception if no such prompt can be found. The returned object is an
91       instance of Net::CLI::Interact::ActionSet.
92
93   has_prompt( $name )
94       Returns true if a prompt of the given $name exists in the loaded
95       phrasebooks.
96
97   prompt_names
98       Returns a list of the names of the current loaded Prompts.
99
100   macro( $name )
101       Returns the Macro associated to the given $name, or throws an exception
102       if no such macro can be found. The returned object is an instance of
103       Net::CLI::Interact::ActionSet.
104
105   has_macro( $name )
106       Returns true if a macro of the given $name exists in the loaded
107       phrasebooks.
108
109   macro_names
110       Returns a list of the names of the current loaded Macros.
111

PHRASEBOOK FORMAT

113   Prompt
114       A Prompt is a named regular expression which matches the content of a
115       single line of text. Here is an example:
116
117        prompt configure
118            match /\(config[^)]*\)# ?$/
119
120       On the first line is the keyword "prompt" followed by the name of the
121       Prompt, which must be a valid Perl identifier (letters, numbers,
122       underscores only).
123
124       On the immediately following line is the keyword "match" followed by a
125       regular expression, enclosed in two forward-slash characters.
126       Currently, no alternate bookend characters are supported, nor are
127       regular expression modifiers (such as "xism") outside of the match, but
128       you can of course include them within.
129
130       The Prompt is used to find out when the connected CLI has emitted all
131       of the response to a command. Try to make the Prompt as specific as
132       possible, including line-end anchors. Remember that it will be matched
133       against one line of text, only.
134
135   Macro
136       In general, Macros are alternating sequences of commands to send to the
137       connected CLI, and regular expressions to match the end of the returned
138       response. Macros are useful for issuing commands which have
139       intermediate prompts, or confirmation steps. They also support the
140       slurping of additional output when the connected CLI has split the
141       response into pages.
142
143       At its simplest a Macro can be just one command:
144
145        macro show_int_br
146            send show ip int br
147            match /> ?$/
148
149       On the first line is the keyword "macro" followed by the name of the
150       Macro, which must be a valid Perl identifier (letters, numbers,
151       underscores only).
152
153       On the immediately following line is the keyword "send" followed by a
154       space and then any text up until the end of the line, and if you want
155       to include whitespace at the beginning or end of the command, use
156       quotes. This text is sent to the connected CLI as a single command
157       statement. The next line contains the keyword "match" followed by the
158       Prompt (regular expression) which will terminate gathering of returned
159       output from the sent command.
160
161       Macros support the following features:
162
163       Automatic Matching
164           Normally, you ought always to specify "send" statements along with
165           a following "match" statement so that the module can tell when the
166           output from your command has ended. However you can omit any Match
167           and the module will insert either the current "prompt" value if set
168           by the user, or the last Prompt from the last Macro. So the
169           previous example could be re-written as:
170
171            macro show_int_br
172                send show ip int br
173
174           You can have as many "send" statements as you like, and the Match
175           statements will be inserted for you:
176
177            macro show_int_br_and_timestamp
178                send show ip int br
179                send show clock
180
181           However it is recommended that this type of sequence be implemented
182           as individual commands (or separate Macros) rather than a single
183           Macro, as it will be easier for you to retrieve the command
184           response(s). Normally the Automatic Matching is used just to allow
185           missing off of the final Match statement when it's the same as the
186           current Prompt.
187
188       Format Interpolation
189           Each "send" statement is in fact run through Perl's "sprintf"
190           command, so variables may be interpolated into the statement using
191           standard "%" fields.  For example:
192
193            macro show_int_x
194                send show interface %s
195
196           The method for passing variables into the module upon execution of
197           this Macro is documented in Net::CLI::Interact::Role::Engine. This
198           feature is useful for username/password prompts.
199
200       Named Match References
201           If you're going to use the same Match (regular expression) in a
202           number of Macros, then set it up as a Prompt (see above) and refer
203           to it by name, instead:
204
205            prompt priv_exec
206                match /# ?$/
207
208            macro to_priv_exec
209                send enable
210                match /[Pp]assword: ?$/
211                send %s
212                match priv_exec
213
214           As you can see, in the case of the last Match, we have the keyword
215           "match" followed by the name of a defined Prompt. To match multiple
216           defined Prompts use this syntax (with as many named references as
217           you like):
218
219            macro to_privileged
220                send enable
221                match username_prompt or priv_exec
222
223       Continuations
224           Sometimes the connected CLI will not know it's talking to a program
225           and so paginate the output (that is, split it into pages). There is
226           usually a keypress required between each page. This is supported
227           via the following syntax:
228
229            macro show_run
230                send show running-config
231                follow / --More-- / with ' '
232
233           On the line following the "send" statement is the keyword "follow"
234           and a regular expression enclosed in forward-slashes. This is the
235           Match which will, if seen in the command output, trigger the
236           continuation. On the line you then have the keyword "with" followed
237           by a space and some text, until the end of the line. If you need to
238           enclose whitespace use quotes, as in the example.
239
240           The module will send the continuation text and gobble the matched
241           prompt from the emitted output so you only have one complete piece
242           of text returned, even if split over many pages. The sent text can
243           contain metacharacters such as "\n" for a newline.
244
245           Note that in the above example the "follow" statement should be
246           seen as an extension of the "send" statement. There is still an
247           implicit Match prompt added at the end of this Macro, as per
248           Automatic Matching, above.
249
250       Line Endings
251           Normally all sent command statements are appended with a newline
252           (or the value of "ors", if set). To suppress that feature, use the
253           keyword "put" instead of "send". However this does not prevent the
254           Format Interpolation via "sprintf" as described above (simply use
255           "%%" to get a literal "%").
256
257
258
259perl v5.34.0                      2022-01-21 Net::CLI::Interact::Phrasebook(3)
Impressum