The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Getopt-GUI-Long-0.4
River stage zero No dependents
/ Getopt::GUI::Long

NAME

Getopt::GUI::Long

SYNOPSIS

  use Getopt::GUI::Long;

  # pass useful config options to Configure
  Getopt::GUI::Long::Configure(qw(display_help no_ignore_case capture_output));
  GetOptions(\%opts,
             ["h|help", "Show help for command line options"],
             ["some-flag=s", "perform some flag based on a value"]);

  # or

  GetOptions(["h|help", "Show help for command line options"] => \$help,
             ["some-flag=s", "perform some flag based on a value"] => \$flag);

DESCRIPTION

This module is a wrapper around Getopt::Long that extends the value of the originial Getopt::Long module to add a simple graphical user interface option screen if no arguments are passed to the program. Thus, the arguments to actually use are built based on the results of the user interface. If arguments were passed to the program, the user interface is not shown and the program executes as it normally would and acts just as if Getopt::Long::GetOptions had been called instead.

HISTORY

This module was originally named Getopt::Long::GUI but the Getopt::Long author wanted to reserve the Getopt::Long namespace entirely for himself and thus it's been recently renamed to Getopt::GUI::Long instead. The class tree isn't as clean this way, as this module still inherits from Getopt::Long but it everything still works of course.

USAGE

The Getopt::GUI::Long module works identically to the Getopt::Long module, but does offer a few extra features.

Option format:

Option strings passed should be formatted in one of the following ways:

Empty String

Empty strings are ignored by the non-GUI version of the command, but are treated as vertical separators between questions when displaying the GUI screen.

Standard flag specification string
   EG: "some-flag|optional-flag=s"

This is the standard method by which Getopt::Long does things and is merely treated the same way here. In this case, the text presented to the user screen will be the first name in the list ("some-flag") in the above option. The type of wdget displayed with the text will depend on the optional =s/i/whatever flag and will be either a checkbox, entry box, ...

Array Reference
   EG: ["some-flag|optional-flag=s", 'Prompt text', OTHER],

The values passed in this array are as follows:

0: Standard flag specification string

Same as always, and as above.

1: Prompt text about flag

The help text that should be shown to the user in the graphical interface. In the example above rather than "some-flag" being shown, "Prompt text" will be shown next to the widget instead.

If the prompt text is equal to "!GUI" then this option will not be displayed (automatically at least) within the GUI.

2...: OTHER options
required => 1

Forces a screen option to be filled out by the user.

[others TBD]

Special Flag Names

Flags that start with GUI: are not passed to the normal Getopt::Long routines and are instead for internal GUI digestion only. If the GUI screen is going to be displayed (remember: the user didn't specify any options), these extra options control how the GUI behaves.

GUI:guionly
  EG:  ['GUI:guionly', { type => 'checkbox', name => 'myguiflag'}]

Specifies a valid QWizard question(s) to only be shown when the gui is displayed, and the specification is ignored during normal command line usage.

GUI:separator
  EG:  ['GUI:separator', 'Task specific options:']

Inserts a label above a set of options to identify them as a group.

GUI:otherargs_text
  EG:  ['GUI:otherargs', 'Files to process:']

Normally the GUI screen shows a "Other Arguments:" option at the bottom of the main GUI screen to allow users to entry additional flags (needed for file names, etc, and other non-option arguments to be passed). However, since it doesn't know what these arguments should be it can only provide a generic "Other Arguments:" description. This setting lets you change that text to something specific to what your application experts, such as "Files:" or "HTML Files:" or something that helps the user understand what is expected of them.

If you want to self-handle the argument prompting using other QWizard constructs, then use the nootherargs token described below instead.

GUI:nootherargs
  EG:  ['GUI:nootherargs', 1]

Normally the GUI screen shows a "Other Arguments:", or programmer described text as described above, option at the bottom of the main GUI screen. If you're going to handle the additional arguments yourself in some way (using either some GUI:guionly or (GUI:otherprimaries and GUI:submodules) flags), then you should specify this so the other arguments field is not shown. You're expected, in your self-handling code, to set the __otherargs QWizard parameter to the final arguments that should be passed on.

GUI:otherprimaries
  EG:  ['GUI:otherprimaries', primaryname => 
                              { title => '...', questions => [...] }]

Defines other primaries to be added to the QWizard primary set.

GUI:submodules
  EG:  ['GUI:submodules', 'primaryname']

Defines a list of other primaries that should be called after the initial one.

GUI:post_answers
  EG:  ['GUI:post_actions', sub { do_something(); }]

Defines an option for QWizard post_answers subroutines to run.

GUI:actions
  EG:  ['GUI:post_actions', sub { do_something(); }]

Defines an option for QWizard actions subroutines to run.

GUI:actions
  EG:  ['GUI:hook_finished', sub { do_something(); }]

Defines subroutine(s) to be called after the GUI has completely finished.

GUI:

CONFIGURATION

If you call Getopt::GUI::Long's Configure routine, it will accept a number of configure tokens and will pass the remaining ones to the Getopt::Long Configure routine. The tokens that it recognizes itself are described below:

display_help

The Getopt::GUI::Long package will auto-display help messages based on the text included in the GetOptions call. No more writing those silly usage() functions!

Note that this differs from the Getopt::Long's implementation of the auto_help token in that the information is pulled from the extended GetOptions called instead of the pod documentation.

capture_output

This tells the Getopt::GUI::Long module that it should caputure the resulting STDOUT and STDERR results from the script and display the results in a window once the script has finished.

PORTABILITY

If programs desire to not require this module, the following code snippit can be used instead which will not fail even if this module is not available. To be used this way, the LocalGetOptions and LocalOptionsMap functions should be copied to your perl script.

  LocalGetOptions(\%opts,
                  ["h|help", "Show help for command line options"],
                  ["some-flag=s", "perform some flag based on a value"]);

  sub LocalGetOptions {
      if (eval {require Getopt::GUI::Long;}) {
        import Getopt::GUI::Long;
        # optional configure call
        Getopt::Long::Configure(qw(display_help no_ignore_case capture_output));
        return GetOptions(@_);
      }
      require Getopt::Long;
      import Getopt::Long;
      # optional configure call
      Getopt::Long::Configure(qw(auto_help no_ignore_case));
      GetOptions(LocalOptionsMap(@_));
  }

  sub LocalOptionsMap {
      my ($st, $cb, @opts) = ((ref($_[0]) eq 'HASH') 
                            ? (1, 1, $_[0]) : (0, 2));
      for (my $i = $st; $i <= $#_; $i += $cb) {
        if ($_[$i]) {
            next if (ref($_[$i]) eq 'ARRAY' && $_[$i][0] =~ /^GUI:/);
            push @opts, ((ref($_[$i]) eq 'ARRAY') ? $_[$i][0] : $_[$i]);
            push @opts, $_[$i+1] if ($cb == 2);
        }
      }
      return @opts;
  }

AUTHOR

Wes Hardaker, hardaker@users.sourceforge.net

SEE ALSO

perl(1)

modules: QWizard