1Net::CLI::Interact::PhrUasseerboCookn(t3r)ibuted Perl DoNceutm:e:nCtLaIt:i:oInnteract::Phrasebook(3)
2
6 Net::CLI::Interact::Phrasebook - Load command phrasebooks from a
7 Library
8
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 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 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 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 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 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
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 /dir1/file1
49 /dir1/file2
50 /dir1/dir2/file3
51 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 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
66 new( \%options )
67 This takes the following options, and returns a loaded phrasebook
68 object:
69 "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 "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 "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 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 has_prompt( $name )
94 Returns true if a prompt of the given $name exists in the loaded
95 phrasebooks.
96 prompt_names
98 Returns a list of the names of the current loaded Prompts.
99 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 has_macro( $name )
106 Returns true if a macro of the given $name exists in the loaded
107 phrasebooks.
108 macro_names
110 Returns a list of the names of the current loaded Macros.
111
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 prompt configure
118 match /\(config[^)]*\)# ?$/
119 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 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 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 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 At its simplest a Macro can be just one command:
144 macro show_int_br
146 send show ip int br
147 match /> ?$/
148 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 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 Macros support the following features:
162 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 macro show_int_br
172 send show ip int br
173 You can have as many "send" statements as you like, and the Match
175 statements will be inserted for you:
176 macro show_int_br_and_timestamp
178 send show ip int br
179 send show clock
180 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 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 macro show_int_x
194 send show interface %s
195 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 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 prompt priv_exec
206 match /# ?$/
207 macro to_priv_exec
209 send enable
210 match /[Pp]assword: ?$/
211 send %s
212 match priv_exec
213 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 macro to_privileged
220 send enable
221 match username_prompt or priv_exec
222 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 macro show_run
230 send show running-config
231 follow / --More-- / with ' '
232 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 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 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 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 "%").
256perl v5.32.1 2021-01-27 Net::CLI::Interact::Phrasebook(3)