NAME

CLI::Gwrap.pm - GUI wrapper for command line scripts and programs

VERSION

version 0.030

SYNOPSIS

 use CLI::Gwrap;

 CLI::Grawp->new(
    command     => 'ls'             # the CLI name
    description => 'List info ...', # from the man page
    ...                             # see Example below
 );

DESCRIPTION

CLI::Gwrap builds a GUI wrapper around a Command Line Interface (CLI) script or program. The GUI presents the CLI options to the user and then runs the CLI program.

The specific GUI is chosen with a plugin system. To write a new Gwrapper, follow the default CLI::Gwrapper::wxGrid as an example.

Methods

my $gwrap = CLI::Gwrap->new( %hash )

Creates a new GUI Wrapper. %hash describes the particulars of how the GUI should look and behave.

CLI::Gwrap is intended to make traditionally difficult CLI programs more easily accessible. To help, there are places where CLI::Gwrap accepts either a simple name string, or a two-element array reference where the first element is the 'actual' name (as used by the CLI program) and the second element is a more descriptive alias. In the following documentation, those places are denoted by 'NAME'.

Most CLI programs have at least one option that is not explicitly named. For example:

    ls foo*

The "foo*" option is not 'named', but 'ls' expects it to be a file glob. In CLI::Gwrap, this option should be denoted by main_opt in the call to CLI::Gwrap->new(). The NAME should be set to the empty string (''), or more helpfully, aliased to an empty string:

    [ '', 'file or directory GLOB pattern' ]

which shows the explanation in the GUI, but adds no explicit option on the CLI program command line.

%hash keys available to new() are:

command => NAME

The CLI program name.

main_opt => OPTION

Most CLI programs take one (or more) unnamed options. Specify that option here. For a description of OPTION, see OPTION FUNCTIONS below.

description => 'text'

A description of the CLI program, possibly taken from the man page. This is typically displayed by the GUI when the mouse hovers over the CLI program name.

gwrapper_name => 'Wrapper_Name'

Select a different Graphic Wrappers pluggin. The default wrapper is 'wxGrid'. Wrappers are installed in the CLI/Gwrapper directory.

verbatim => true

Most CLI programs take options with either a single dash (single letter) or double dash preceding them. CLI::Gwrap by default automatically prepends a single dash to single letter options, and a double dash to longer options. Setting a true verbatim option suppresses this behavior, options must then be entered exactly as the CLI program expects them.

help => 'help_option'

Many CLI programs can be induced to print out a help message of some kind. If the help key is used, the value should be the CLI program option that produces the help message. CLI::Gwrap will add a 'Help' button to the GUI which, when pressed, will create a text window of the output (from STDOUT or STDERR).

persist => true

The GUI normally closes as soon as the 'Execute' button is pressed. <persist> suppresses automatic closing - the user must press the 'Close' button.

opts => [ common OPTIONS ]
advanced => [ advanced OPTIONS ]

The CLI program options are listed in these array references. If advanced is included, the CLI::Gwrap adds an 'Advanced' button which exposes the less common options (which are normally hidden).

The elements of these arrays are built by calling the OPTION FUNCTIONS (see below).

exec_callback => sub { ... }

When the 'Execute' (or 'Help') button in the GUI is clicked, CLI::Gwrapper by default calls a function that calls IPC::Run::run(...) to execute the CLI script or program. You can set your own exec_callback function here to override that behavior. This makes it easy to use CLI::Gwrap directly in a script (as opposed to writing a wrapper for an existing script). The callback function should be something like this:

    sub my_exec_callback {
        my ($self, $cmd_ref) = @_;  # $cmd_ref is an ArrayRef consisting
                                    #   of the command and all the options,
                                    #   as collected from the GUI

        my ($stdout, $stderr);
        local (*STDOUT, *STDERR);
        open(STDOUT, ">", \$stdout)
            or die "failed to redirect STDOUT\n";
        open(STDERR, ">", \$stderr)
            or die "failed to redirect STDERR\n";

        ############################################
        #
        # Your script-specific execution here
        #
        ############################################

        return ($?, $stdout, $stderr);
    }
timeout => number

The timeout, in seconds, used by IPC::Run::run(...) when calling the script or program (when the 'Execute' or 'Help' button is clicked in the GUI). The default is 10 (seconds).

$gwrap->run

Runs the CLI::Gwrap object by calling its run method (which is required by the CLI::Gwrapper role). For (e.g.) the wxGrid Gwrapper, this calls Wx::MainLoop.

$gwrap->title( [ 'new title' ])

Get or set the GUI window title. The title is normally set to the unadorned command name when the GUI is first presented. When the 'Execute' button is clicked, the title is changed to the command name followed by all the options as specified by the user.

OPTION FUNCTIONS

Option functions are used in the opts and advanced arguments to new() to populate the CLI program option fields in the GUI.

Option functions all take a NAME as the first argument, and a 'description' as the second. The description is typically displayed when the user hovers the mouse over the option NAME or field. Additional named options may follow. Named options include (see CLI::Gwrap::Opt for a full list):

state => 'initial state'

The initial state of the option, interpreted in the context of the option (e.g: check is true/false, string is a string, radio is one of the choices).

label => 'override label'

A string to override the normal label derived from the NAME. This can be set (e.g) to the empty string to disply no label.

width => pixels

The number of pixels for the width of a string, integer, or increment widget.

choices => [ qw( array of choices ) ]

Passes a reference to an array of choices for a radio option.

joiner => 'string'

The 'joiner' to use for the CLI command line between the option name and the option value. The default is for single-letter options to use a single space:

    ... -x 4 ...

and for long options to use an equals sign:

    ... --long_opt=ABC

The available option functions are:

check( NAME, 'description', %opts )

Create a checkbox in the GUI for 'flag' type options. $opt-{state}> is interpreted as true or false.

radio( NAME, 'description', %opts )

Create a radio button or drop-down combo box. Set the choices with the choices named option:

    choices => [ qw( the array of choices ) ],

The first element of the arrayref must be the CLI program's default.

If the state named option is declared, it must be one of the choices.

If the default is selected, this NAME will not be explicitly called out on the command line.

string( NAME, 'description', %opts )
hash( NAME, 'description', %opts )

Create a text-entry widget. If the state is specified, the initial value in the text-entry widget is set.

string is for single-use options.

hash is used for muliple-use options: the value is split into tokens (on whitespace), and NAME is used once for each token. For example, if the user enters "AAA bbb XyZ", the CLI program is called with:

        '... -x AAA -x bbb -x XyZ ...'

or

        '... --long_opt=AAA --long_opt=bbb --long_opt=XyZ ...'
integer( NAME, 'description', %opts )
float( NAME, 'description', %opts )

Create an integer or floating point number entry. <float> allows normal perl floating point representations.

incremental( NAME, 'description', %opts )

Create an input that looks like an integer entry, but when the CLI program is called, CLI::Gwrap will specify NAME the number of times set in the spinner. For example, a multi-level verbose flag can be specified with:

        incremental( [ 'v', 'verbose' ] )

If the user sets the value to 3, the CLI program is called with:

        '... -v -v -v ...'
label( NAME, 'description', %opts )

This is not actually an option, and no option is passed to the CLI program from a label. It is used to create non-option tags and spacers in the GUI.

EXAMPLE

Here is part of the gwrap_ls.pl example, the entire listing can be found in the /bin directory of the distribution package:

 use CLI::Gwrap qw(check radio string hash integer float incremental);

 my $gwrap = CLI::Gwrap->new(
    command     => 'ls',
    description => 'list directory contents',
    columns     => 4,
    help        => '--help',
    persist     => 1,
    main_opt    => hash(
        [
            '',             # this option has no name
            'pattern(s)',   # alias (description)
        ],
        # 'hover' help
        qq[shell glob pattern(s) to match file or directory names],
    ),
    opts     => [
        check(
            'all',  # option name
            'do not ignore entries starting with .',
        ),

        check(
            [
                'C',        # option name
                'columns',  # either a long name or help for a short name
            ],
            'list entries by columns'
        ),
     .
     .
     .
    ],

    advanced    => [
        check(
            'almost-all',
            'do not list implied . and ..',
        ),

        radio(
            'color',
            qq[colorize the output. Defaults to 'always' or can be 'never' or 'auto'],
            choices => ['always', 'never', 'auto'], # the choices
        ),
    ]

 );

AUTHOR

Reid Augustin <reid@hellosix.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Reid Augustin.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.