NAME

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,
             ["GUI:separator",   "Important Flags:"],
             ["f|some-flag=s",   "A flag based on a string"],
             ["o|other-flag",    "A boloean"],
            );

  # or use references instead of a hash (less tested, however):

  GetOptions(["some-flag=s",  "perform some flag based on a value"] => \$flag,
             ["other-flag=s", "perform some flag based on a value"] => \$other);

  # displays auto-help given the input above:

  % opttest -h
  Usage: opttest [OPTIONS] Other Arguments

  OPTIONS:

  Important Flags:
     -f STRING             A flag based on a string
     -o                    A boloean

  Help Options:
     -h                    Display help options -- short flags preferred
    --help                 Display help options -- long flags preferred
    --help-full            Display all help options -- short and long



  # or long help:

  % opttest --help
  Usage: opttest [OPTIONS] Other Arguments

  OPTIONS:

  Important Flags:
    --some-flag=STRING     A flag based on a string
    --other-flag           A boloean

  Help Options:
     -h                    Display help options -- short flags preferred
    --help                 Display help options -- long flags preferred
    --help-full            Display all help options -- short and long

  # or a GUI screen:

  (see http://www.dnssec-tools.org/images/getopt_example.png )

DESCRIPTION

  This module is a wrapper around Getopt::Long that extends the value of
  the original Getopt::Long module to:

  1) 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.

  2) provide an auto-help mechanism such that -h and --help are
     handled automatically.  In fact, calling your program with -h
     will default to showing the user a list of short-style arguments
     when one exists for the option.  Similarly --help will show the
     user a list of long-style when possible.  --help-full will list
     all potential arguments for an option (short and long both).

  It's designed to make the creation of graphical shells trivial
  without the programmer having to think about it much as well as
  providing automatic good-looking usage output without the
  programmer needing to write usage() functions.

  This also can turn normal command line programs into web CGI scripts
  as well (automatically).  If the Getopt::GUI::Long program is
  installed as a CGI script then it will automatically prompt the user
  for the same variables.

USAGE

Special Flag Names

Some of these options requires some knowledge of the QWizard programming system. Knowledge of QWizard should only be required if you want to make use of those particular extra features.

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:screen

  EG:  ['GUI:screen', 'Next Screen Title', ...]
    

Specifies that a break in the option requests should occur and the remaining options should appear on another screen(s). This allows applications with a lot of options to reduce the complexity it offers users and offers a more "wizard" like approach to helping them decide what they're trying to do.

You can also make this next screen definition conditional by defining an earlier option that may be, say, a boolean flag called "feature_flag". Using this you can then only go into the next screen if the "feature_flag" was set by doing the following:

        ['feature-flag',
         'turn on a special feature needing more options'],

        ['GUI:screen', 'Next Screen Title', doif => 'feature-flag']
        ['feature-arg1', 'extra argument #1 for special feature'],
        ...
    

Also, if you need to do more complex calculations use the qwparam() function of the passed in QWizard object in a subroutine reference instead:

        ['feature1','Turn on feature #1"],
        ['feature2','Turn on feature #2"],

        ['GUI:screen', 'Next Screen Title', 
         doif => sub { 
           return ($_[1]->qwparam('feature1') && $_[1]->qwparam('feature2'));
        }]
    

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:nosavebutton

  EG:  ['GUI:nosavebutton', 1]
    

Normally the GUI screen offers a "save" menu that lets users save their current screen settings for future calls. Using this setting turns off this behavior so the button isn't shown.

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_answers', sub { do_something(); }]
    

Defines an option for QWizard post_answers subroutines to run.

GUI:actions

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

Defines an option for QWizard actions subroutines to run.

GUI:hook_finished

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

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

GUI:run_button

  EG: ['GUI:run_button', 'My Run Button']
    

Defines the text to use for the final "Run" button (which normally just says "Run").

GUI:VERSION

If display_help is defined, and the above token is specified Getopt::GUI::Long takes over the output for --version output as well.

  EG:  ['GUI:VERSION','0.9']
    

Produces the --version help option:

  Help Options:
     -h                    Display help options -- short flags preferred
    --help                 Display help options -- long flags preferred
    --help-full            Display all help options -- short and long
    --version              Display the version number
    

And also auto-handles the --version switch:

  % PROGRAM --version
  Version: 0.9
    

CONFIGURATION

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.

The display_help token will automatically add the following options to the options the application will accept, and will catch and process them as well.

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.

no_gui

This option defaults to not presenting a GUI form for the user to fill out unless they specify --gui as the first and only argument on the command line.

allow_zero

By default the GUI will always pop up if zero-arguments have been specified (or the help info will be displayed if no_gui is set). This options specifies that zero arguments is a normal usage case. Thus the only way to force the GUI or help to appear will be the command line --gui flag.

Using the QWizard object for other purposes

  $Getopt::GUI::Long::GUI_qw->set_progress(3/5)
    if ($Getopt::GUI::Long::GUI_qw);

PORTABILITY

  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::GUI::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;
  }

 sub LocalGetOptions {
     # force the library by using $ENV{'QWIZARD_GENERATOR'}
     # if Gtk2, Tk, HTML or Readline generators are required, set the
     # QWIZARD_GENERATOR ENV variable either externally or in this
     # script Example: Force QWizard to use Tk instead of the
     # preferred default of Gtk2 like this:
     $ENV{'QWIZARD_GENERATOR'} = 'Tk' if (not exists($ENV{'QWIZARD_GENERATOR'}));
 
     # ... conitune with the rest of the LocalGetOptions shown above

Usage as a CGI Script

It will not present the box for generic additional arguments since this is not safe to do. If you trust your users (ie, you have an authentication system in place) then you can set the allowcgiargs GUI variable to make this box appear. Example invocation (not generally recommended):

  ['GUI:allowcgiargs',1]

It also allows you to not present certain options to web users that you will to command line users (some options may not be safe for CGI use). You can do this by setting the nocgi variable in option definitions you wish to disallow via CGI. E.G., if you had an option to specify a location where to load configuration a file from, this would likely be unsafe to publish in a CGI script. So remove it:

  ["c|config-file","Load a specific configuration file", nocgi => 1]

EXAMPLES

AUTHOR

COPYRIGHT and LICENSE

Copyright (c) 2006-2007, Wes Hardaker. All rights reserved

Getopt::GUI::Long is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

modules: QWizard

HISTORY