1Long(3) User Contributed Perl Documentation Long(3)
2
6 Getopt::GUI::Long
7
9 use Getopt::GUI::Long;
10 # pass useful config options to Configure
12 Getopt::GUI::Long::Configure(qw(display_help no_ignore_case capture_output));
13 GetOptions(\%opts,
14 ["GUI:separator", "Important Flags:"],
15 ["f⎪some-flag=s", "A flag based on a string"],
16 ["o⎪other-flag", "A boloean"],
17 );
18 # or use references instead of a hash (less tested, however):
20 GetOptions(["some-flag=s", "perform some flag based on a value"] => \$flag,
22 ["other-flag=s", "perform some flag based on a value"] => \$other);
23 # displays auto-help given the input above:
25 % opttest -h
27 Usage: opttest [OPTIONS] Other Arguments
28 OPTIONS:
30 Important Flags:
32 -f STRING A flag based on a string
33 -o A boloean
34 Help Options:
36 -h Display help options -- short flags preferred
37 --help Display help options -- long flags preferred
38 --help-full Display all help options -- short and long
39 # or long help:
41 % opttest --help
43 Usage: opttest [OPTIONS] Other Arguments
44 OPTIONS:
46 Important Flags:
48 --some-flag=STRING A flag based on a string
49 --other-flag A boloean
50 Help Options:
52 -h Display help options -- short flags preferred
53 --help Display help options -- long flags preferred
54 --help-full Display all help options -- short and long
55 # or a GUI screen:
57 (see http://net-policy.sourceforge.net/images/getopt_example.png )
59
61 This module is a wrapper around Getopt::Long that extends the value of
62 the original Getopt::Long module to:
63 1) add a simple graphical user interface option screen if no
65 arguments are passed to the program. Thus, the arguments to
66 actually use are built based on the results of the user
67 interface. If arguments were passed to the program, the user
68 interface is not shown and the program executes as it normally
69 would and acts just as if Getopt::Long::GetOptions had been
70 called instead.
71 2) provide an auto-help mechanism such that -h and --help are
73 handled automatically. In fact, calling your program with -h
74 will default to showing the user a list of short-style arguments
75 when one exists for the option. Similarly --help will show the
76 user a list of long-style when possible. --help-full will list
77 all potential arguments for an option (short and long both).
78 It's designed to make the creation of graphical shells trivial
80 without the programmer having to think about it much as well as
81 providing automatic good-looking usage output without the
82 programmer needing to write usage() functions.
83
85 This module was originally named Getopt::Long::GUI but the Getopt::Long
86 author wanted to reserve the Getopt::Long namespace entirely for him‐
87 self and thus it's been recently renamed to Getopt::GUI::Long instead.
88 The class tree isn't as clean this way, as this module still inherits
89 from Getopt::Long but it everything still works of course.
90
92 The Getopt::GUI::Long module can work identically to the Getopt::Long
93 module but really benefits from some slightly different usage conven‐
94 tions described below.
95 Option format:
97 Option strings passed should be formatted in one of the following ways:
99 Empty String
101 Empty strings are ignored by the non-GUI version of the command,
102 but are treated as vertical separators between questions when dis‐
103 playing the GUI screen.
104 Standard flag specification string
106 EG: "some-flag⎪optional-flag=s"
107 This is the standard method by which Getopt::Long does things and
109 is merely treated the same way here. In this case, the text pre‐
110 sented to the user screen will be the first name in the list
111 ("some-flag") in the above option. The type of wdget displayed
112 with the text will depend on the optional =s/i/whatever flag and
113 will be either a checkbox, entry box, ...
114 Array Reference
116 EG: ["some-flag⎪optional-flag=s", 'Prompt text', OTHER],
117 The values passed in this array are as follows:
119 0: Standard flag specification string
121 Same as always, and as above.
122 1: Prompt text about flag
124 The help text that should be shown to the user in the graphical
125 interface. In the example above rather than "some-flag" being
126 shown, "Prompt text" will be shown next to the widget instead.
127 If the prompt text is equal to "!GUI" then this option will not
129 be displayed (automatically at least) within the GUI.
130 2...: OTHER options
132 Beyond the name and description, key value pairs can indicate
133 more about how the option should be handled.
134 required => 1
136 Forces a screen option to be filled out by the user.
137 question => { QUESTION FORM }
139 question => [{ QUESTION1}, {QUESTION2}, ...]
140 These allows you to build custom QWizard widgets to meet a
141 particular question need. It's highly useful for doing
142 menus and single choice fields that normally command line
143 options don't handle well. For example consider a numeric
144 priority level between 0 and 10. The following question
145 definition will give them a menu rather than a fill in the
146 blank field:
147 ['priority=i','Priority Level',
149 question => { type => 'menu', values => [1..10] }]
150 Note you can specify multiple question widgets if needed as
152 well, though this will probably be rare in usage.
153 QWizard question tokens
155 Any of the following items can be passed as well, which
156 will be added to the QWizard question structure. See the
157 QWizard documantion on "QUESTION DEFINITIONS" for details
158 on the usage of these.
159 type
161 helpdesc
162 helptext
163 default
164 check_value
165 doif
166 submit
167 refresh_on_change
168 handle_results
169 text
170 (Warning: Replaces the text already extracted from the
171 prompt text described above).
172 name
174 (Warning: Replaces the option name extracted from the
175 position 0 standard flag specification string above.
176 Do not use this unless you really know what you're
177 doing.)
178 [others TBD]
180
182 Flags that start with GUI: are not passed to the normal Getopt::Long
183 routines and are instead for internal GUI digestion only. If the GUI
184 screen is going to be displayed (remember: only if the user didn't
185 specify any options), these extra options control how the GUI behaves.
186 Some of these options requires some knowledge of the QWizard program‐
188 ming system. Knowledge of QWizard should only be required if you want
189 to make use of those particular extra features.
190 GUI:guionly
192 EG: ['GUI:guionly', { type => 'checkbox', name => 'myguiflag'}]
193 Specifies a valid QWizard question(s) to only be shown when the gui
195 is displayed, and the specification is ignored during normal com‐
196 mand line usage.
197 GUI:separator
199 EG: ['GUI:separator', 'Task specific options:']
200 Inserts a label above a set of options to identify them as a group.
202 GUI:screen
204 EG: ['GUI:screen', 'Next Screen Title', ...]
205 Specifies that a break in the option requests should occur and the
207 remaining options should appear on another screen(s). This allows
208 applications with a lot of options to reduce the complexity it
209 offers users and offers a more "wizard" like approach to helping
210 them decide what they're trying to do.
211 You can also make this next screen definition conditional by defin‐
213 ing an earlier option that may be, say, a boolean flag called "fea‐
214 ture_flag". Using this you can then only go into the next screen
215 if the "feature_flag" was set by doing the following:
216 ['feature-flag',
218 'turn on a special feature needing more options'],
219 ['GUI:screen', 'Next Screen Title', doif => 'feature-flag']
221 ['feature-arg1', 'extra argument #1 for special feature'],
222 ...
223 Also, if you need to do more complex calculations use the qwparam()
225 function of the passed in QWizard object in a subroutine reference
226 instead:
227 ['feature1','Turn on feature #1"],
229 ['feature2','Turn on feature #2"],
230 ['GUI:screen', 'Next Screen Title',
232 doif => sub {
233 return ($_[1]->qwparam('feature1') && $_[1]->qwparam('feature2'));
234 }]
235 GUI:otherargs_text
237 EG: ['GUI:otherargs', 'Files to process:']
238 Normally the GUI screen shows a "Other Arguments:" option at the
240 bottom of the main GUI screen to allow users to entry additional
241 flags (needed for file names, etc, and other non-option arguments
242 to be passed). However, since it doesn't know what these arguments
243 should be it can only provide a generic "Other Arguments:" descrip‐
244 tion. This setting lets you change that text to something specific
245 to what your application experts, such as "Files:" or "HTML Files:"
246 or something that helps the user understand what is expected of
247 them.
248 If you want to self-handle the argument prompting using other QWiz‐
250 ard constructs, then use the nootherargs token described below
251 instead.
252 GUI:nootherargs
254 EG: ['GUI:nootherargs', 1]
255 Normally the GUI screen shows a "Other Arguments:", or programmer
257 described text as described above, option at the bottom of the main
258 GUI screen. If you're going to handle the additional arguments
259 yourself in some way (using either some GUI:guionly or (GUI:other‐
260 primaries and GUI:submodules) flags), then you should specify this
261 so the other arguments field is not shown. You're expected, in
262 your self-handling code, to set the __otherargs QWizard parameter
263 to the final arguments that should be passed on.
264 GUI:nosavebutton
266 EG: ['GUI:nosavebutton', 1]
267 Normally the GUI screen offers a "save" menu that lets users save
269 their current screen settings for future calls. Using this setting
270 turns off this behavior so the button isn't shown.
271 GUI:otherprimaries
273 EG: ['GUI:otherprimaries', primaryname =>
274 { title => '...', questions => [...] }]
275 Defines other primaries to be added to the QWizard primary set.
277 GUI:submodules
279 EG: ['GUI:submodules', 'primaryname']
280 Defines a list of other primaries that should be called after the
282 initial one.
283 GUI:post_answers
285 EG: ['GUI:post_answers', sub { do_something(); }]
286 Defines an option for QWizard post_answers subroutines to run.
288 GUI:actions
290 EG: ['GUI:actions', sub { do_something(); }]
291 Defines an option for QWizard actions subroutines to run.
293 GUI:hook_finished
295 EG: ['GUI:hook_finished', sub { do_something(); }]
296 Defines subroutine(s) to be called after the GUI has completely
298 finished.
299 GUI:run_button
301 EG: ['GUI:run_button', 'My Run Button']
302 Defines the text to use for the final "Run" button (which normally
304 just says "Run").
305 GUI:VERSION
307 If display_help is defined, and the above token is specified
308 Getopt::GUI::Long takes over the output for --version output as
309 well.
310 EG: ['GUI:VERSION','0.9']
312 Produces the --version help option:
314 Help Options:
316 -h Display help options -- short flags preferred
317 --help Display help options -- long flags preferred
318 --help-full Display all help options -- short and long
319 --version Display the version number
320 And also auto-handles the --version switch:
322 % PROGRAM --version
324 Version: 0.9
325
327 If you call Getopt::GUI::Long's Configure routine, it will accept a
328 number of configure tokens and will pass the remaining ones to the
329 Getopt::Long Configure routine. The tokens that it recognizes itself
330 are described below:
331 display_help
333 The Getopt::GUI::Long package will auto-display help messages based
334 on the text included in the GetOptions call. No more writing those
335 silly usage() functions!
336 Note that this differs from the Getopt::Long's implementation of
338 the auto_help token in that the information is pulled from the
339 extended GetOptions called instead of the pod documentation.
340 The display_help token will automatically add the following options
342 to the options the application will accept, and will catch and
343 process them as well.
344 -h Command line help preferring short options if present in the
346 help specification.
347 --help
349 Command line help preferring long options if present in the
350 help specification.
351 --help-full
353 Shows all available option names for a given option
354 capture_output
356 This tells the Getopt::GUI::Long module that it should caputure the
357 resulting STDOUT and STDERR results from the script and display the
358 results in a window once the script has finished.
359
361 The Getopt::GUI::Long qwizard object is stored at
362 $Getopt::GUI::Long::GUI_qw, which is usable for other GUI screens you
363 may need to create after the options screens have been processed. You
364 can also use it during the script to optionally display a progress
365 meter by making use of the QWizard::set_progress function. However,
366 you should test to see if the GUI screen mode was actually used before
367 operating with the object though. As an example:
368 $Getopt::GUI::Long::GUI_qw->set_progress(3/5)
370 if ($Getopt::GUI::Long::GUI_qw);
371
373 If programs desire to not require this module, the following code snip‐
374 pit can be used instead which will not fail even if this module is not
375 available. To be used this way, the LocalGetOptions and LocalOption‐
376 sMap functions should be copied to your perl script.
377 LocalGetOptions(\%opts,
379 ["h⎪help", "Show help for command line options"],
380 ["some-flag=s", "perform some flag based on a value"]);
381 sub LocalGetOptions {
383 if (eval {require Getopt::GUI::Long;}) {
384 import Getopt::GUI::Long;
385 # optional configure call
386 Getopt::GUI::Long::Configure(qw(display_help no_ignore_case capture_output));
387 return GetOptions(@_);
388 }
389 require Getopt::Long;
390 import Getopt::Long;
391 # optional configure call
392 Getopt::Long::Configure(qw(auto_help no_ignore_case));
393 GetOptions(LocalOptionsMap(@_));
394 }
395 sub LocalOptionsMap {
397 my ($st, $cb, @opts) = ((ref($_[0]) eq 'HASH')
398 ? (1, 1, $_[0]) : (0, 2));
399 for (my $i = $st; $i <= $#_; $i += $cb) {
400 if ($_[$i]) {
401 next if (ref($_[$i]) eq 'ARRAY' && $_[$i][0] =~ /^GUI:/);
402 push @opts, ((ref($_[$i]) eq 'ARRAY') ? $_[$i][0] : $_[$i]);
403 push @opts, $_[$i+1] if ($cb == 2);
404 }
405 }
406 return @opts;
407 }
408
410 See the getopttest program in the examples directory for an exmaple
411 script that uses a lot of these features.
412
414 Wes Hardaker, hardaker@users.sourceforge.net
415
417 Copyright (c) 2006-2007, SPARTA, Inc. All rights reserved
418 Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
420 Getopt::GUI::Long is free software; you can redistribute it and/or mod‐
422 ify it under the same terms as Perl itself.
423
425 perl(1)
426 modules: QWizard
428perl v5.8.8 2007-12-20 Long(3)
