The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Getopt-App-1.00
River stage one • 1 direct dependent • 1 total dependent
5 ++
/ Getopt::App

NAME

Getopt::App - Write and test your script with ease

SYNOPSIS

The script file

  #!/usr/bin/env perl
  package My::Script;
  use Getopt::App -complete, -signatures;

  # See "APPLICATION METHODS"
  sub getopt_post_process_argv ($app, $argv, $state) { ... }
  sub getopt_configure ($app) { ... }

  # run() must be the last statement in the script
  run(

    # Specify your Getopt::Long options and optionally a help text
    'h|help            # Output help',
    'v+                # Verbose output',
    'name=s            # Specify a name',
    'completion-script # Print autocomplete script',

    # Here is the main sub that will run the script
    sub ($app, @extra) {
      return print generate_completion_script() if $app->{'completion-script'};
      return print extract_usage()              if $app->{h};
      say $app->{name} // 'no name';            # Access command line options
      return 42;                                # Reture value is used as exit code
    }
  );

Running the script

The example script above can be run like any other script:

  $ my-script --name superwoman; # prints "superwoman"
  $ echo $? # 42

Testing

  use Test::More;
  use Cwd qw(abs_path);
  use Getopt::App -capture;

  # Sourcing the script returns a callback
  my $app = do(abs_path('./bin/myapp'));

  # The callback can be called with any @ARGV
  subtest name => sub {
    my $got = capture($app, [qw(--name superwoman)]);
    is $got->[0], "superwoman\n", 'stdout';
    is $got->[1], '', 'stderr';
    is $got->[2], 42, 'exit value';
  };

  done_testing;

Subcommands

  #!/usr/bin/env perl
  # Define a package to avoid mixing methods after loading the subcommand script
  package My::App::main;
  use Getopt::App -complete;

  # getopt_subcommands() is called by Getopt::App
  sub getopt_subcommands {
    my $app = shift;

    return [
      ['find',   '/path/to/subcommand/find.pl',   'Find things'],
      ['update', '/path/to/subcommand/update.pl', 'Update things'],
    ];
  }

  # run() is only called if there are no matching sub commands
  run(
    'h                 # Print help',
    'completion-script # Print autocomplete script',
    sub {
      my ($app, @args) = @_;
      return print generate_completion_script() if $app->{'completion-script'};
      return print extract_usage();
    }
  );

See "getopt_subcommands" and https://github.com/jhthorsen/getopt-app/tree/main/example for more details.

DESCRIPTION

Getopt::App is a module that helps you structure your scripts and integrates Getopt::Long with a very simple API. In addition it makes it very easy to test your script, since the script file can be sourced without actually being run.

Getopt::App also supports infinite nested subcommands and a method for bundling this module with your script to prevent depending on a module from CPAN.

VARIABLES

DEPTH

$Getopt::App::DEPTH will be increased for each sub command and will be 0 for the first "run".

SUBCOMMAND

$Getopt::App::SUBCOMMAND will be set to the active sub command element. See also "getopt_subcommands".

APPLICATION METHODS

These methods are optional, but can be defined in your script to override the default behavior.

Order of how the methods are called:

  run(@option_spec, $cb)
    -> getopt_pre_process_argv(\@argv)
    -> getopt_configure()
    -> getopt_post_process_argv(\@argv, \%state)
    -> $cb

  run(@option_spec, $cb)
    -> getopt_pre_process_argv(\@argv)
    -> getopt_subcommands()
      -> getopt_load_subcommand($subcommand, \@argv)
        -> getopt_configure()
        -> getopt_post_process_argv(\@argv, \%state)
        -> $cb

getopt_complete_reply

  $app->getopt_complete_reply;

This method will be called instead of the "run" callback when the COMP_LINE and COMP_POINT environment variables are set. The default implementation will call "complete_reply" in Getopt::App::Complete.

See also "Completion" under "import".

getopt_configure

  @configure = $app->getopt_configure;

This method can be defined if you want "Configure" in Getopt::Long to be set up differently. The default return value is:

  qw(bundling no_auto_abbrev no_ignore_case pass_through require_order)

Note that the default "pass_through" item is to enable the default "getopt_post_process_argv" to croak on invalid arguments, since Getopt::Long will by default just warn to STDERR about unknown arguments.

getopt_load_subcommand

  $code = $app->getopt_load_subcommand($subcommand, [@ARGV]);

Takes the subcommand found in the "getopt_subcommands" list and the command line arguments and must return a CODE block. The default implementation is simply:

    $code = do($subcommand->[1]);

getopt_post_process_argv

  $bool = $app->getopt_post_process_argv([@ARGV], {%state});

This method can be used to post process the options. %state contains a key "valid" which is true or false, depending on the return value from "GetOptionsFromArray" in Getopt::Long.

This method can die and optionally set $! to avoid calling the function passed to "run".

The default behavior is to check if the first item in $argv starts with a hyphen, and die with an error message if so:

  Invalid argument or argument order: @$argv\n

getopt_post_process_exit_value

  $exit_value = $app->getopt_post_process_exit_value($exit_value);

A method to be called after the "run" function has been called. $exit_value holds the return value from "run" which could be any value, not just 0-255. This value can then be changed to change the exit value from the program.

  sub getopt_post_process_exit_value ($app, $exit_value) {
    return int(1 + rand 10);
  }

getopt_pre_process_argv

  $app->getopt_pre_process_argv($argv);

This method can be defined to pre-process $argv before it is passed on to "GetOptionsFromArray" in Getopt::Long. Example:

  sub getopt_pre_process_argv ($app, $argv) {
    $app->{first_non_option} = shift @$argv if @$argv and $argv->[0] =~ m!^[a-z]!;
  }

This method can die and optionally set $! to avoid calling the actual "run" function.

getopt_subcommands

  $subcommands = $app->getopt_subcommands;

This method must be defined in the script to enable sub commands. The return value must be either undef to disable subcommands or an array-ref of array-refs like this:

  [["subname", "/abs/path/to/sub-command-script", "help text"], ...]

The first element in each array-ref "subname" will be matched against the first command line option, and when matched, the given subcommand item will be passed on to "getopt_load_subcommand" which must return a code-ref, preferably from "run". The sub command will have $Getopt::App::SUBCOMMAND set to the item found in the list.

getopt_unknown_subcommand

  $exit_value = $app->getopt_unknown_subcommand($argv);

Will be called when "getopt_subcommands" is defined but $argv does not match an item in the list. Default behavior is to die with an error message:

  Unknown subcommand: $argv->[0]\n

Returning undef instead of dying or a number (0-255) will cause the "run" callback to be called.

EXPORTED FUNCTIONS

capture

  use Getopt::App -capture;
  my $app = do '/path/to/bin/myapp';
  my $array_ref = capture($app, [@ARGV]); # [$stdout, $stderr, $exit_value]

Used to run an $app and capture STDOUT, STDERR and the exit value in that order in $array_ref. This function will also capture die. $@ will be set and captured in the second $array_ref element, and $exit_value will be set to $!.

This function is a very slimmed down alternative to "capture" in Capture::Tiny. The main reason why "capture" exists in this package is that if something inside the $app throws an exception, then it will be part of the captured $stderr instead of making capture() throw an exception.

"capture" in Capture::Tiny is however more robust than this function, so please try Capture::Tiny out in case you find an edge case.

extract_usage

  # Default to "SYNOPSIS" from current file
  my $str = extract_usage($section, $file);
  my $str = extract_usage($section);
  my $str = extract_usage();

Will extract a $section from POD $file and append command line option descriptions when called from inside of "run". Command line options can optionally have a description with "spaces-hash-spaces-description", like this:

  run(
    'o|option  # Some description',
    'v|verbose # Enable verbose output',
    sub {
      ...
    },
  );

This function will not be exported if a function with the same name already exists in the script.

new

  my $app = new($class, %args);
  my $app = new($class, \%args);

This function is exported into the caller package so we can construct a new object:

  my $app = Application::Class->new(\%args);

This function will not be exported if a function with the same name already exists in the script.

run

  # Run a code block on valid @ARGV
  run(@option_spec, sub ($app, @extra) { ... });

  # For testing
  my $cb = run(@option_spec, sub ($app, @extra) { ... });
  my $exit_value = $cb->([@ARGV]);

"run" can be used to call a callback when valid command line options are provided. On invalid arguments, warnings will be issued and the program will exit with $? set to 1.

$app inside the callback is a hash blessed to the caller package. The keys in the hash are the parsed command line options, while @extra is the extra unparsed command line options.

@option_spec are the same options as Getopt::Long can take. Example:

  # app.pl -vv --name superwoman -o OptX cool beans
  run(qw(h|help v+ name=s o=s@), sub ($app, @extra) {
    die "No help here" if $app->{h};
    warn $app->{v};    # 2
    warn $app->{name}; # "superwoman"
    warn @{$app->{o}}; # "OptX"
    warn @extra;       # "cool beans"
    return 0;          # Used as exit code
  });

In the example above, @extra gets populated, since there is a non-flag value "cool" after a list of valid command line options.

METHODS

bundle

  Getopt::App->bundle($path_to_script);
  Getopt::App->bundle($path_to_script, $fh);

This method can be used to combine Getopt::App and $path_to_script into a a single script that does not need to have Getopt::App installed from CPAN. This is for example useful for sysadmin scripts that otherwise only depends on core Perl modules.

The script will be printed to $fh, which defaults to STDOUT.

Example usage:

  perl -MGetopt::App -e'Getopt::App->bundle(shift)' ./src/my-script.pl > ./bin/my-script;

import

  use Getopt::App;
  use Getopt::App 'My::Script::Base', -signatures;
  use Getopt::App -capture;

  • Default

      use Getopt::App;

    Passing in no flags will export the default functions "extract_usage", "new" and "run". In addition it will save you from a lot of typing, since it will also import the following:

      use strict;
  use warnings;
  use utf8;
  use feature ':5.16';

  • Completion

      use Getopt::App -complete;

    Same as "Default", but will also load Getopt::App::Complete and import generate_completion_script().

  • Signatures

      use Getopt::App -signatures;

    Same as "Default", but will also import "signatures" in experimental. This requires Perl 5.20+.

  • Class name

      package My::Script::Foo;
  use Getopt::App 'My::Script';

    Same as "Default" but will also make My::Script::Foo inherit from My::Script. Note that a package definition is required.

  • Capture

      use Getopt::App -capture;

    This will only export "capture".

COPYRIGHT AND LICENSE

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org