CXC::Form::Tiny::OptArgs2

This class, in conjunction with CXC::Form::Tiny::Plugin::OptArgs2,
provide a solution to using Form::Tiny and OptArgs2 to manage options
and arguments derived from the command line and from configuration
files.

This class is a wrapper around OptArgs2, automating some of the linkage
between it and Form::Tiny.

  Extension

All of the functionality in this module is performed via methods, which
can be overridden in a subclass to alter

Here are some common things to customize

   Form Classes

Mapping between a class implementing a command or subcommand and its
associated Form::Tiny class is done via the "form_class" method.

   Configuration files

If the application should read configuration files specified on the
command line, override the "config_option" method to return the name of
the configuration option. The option may be scalar or an array.

A modestly complex application will be configured via default values,
configuration files, command line options and arguments, and possibly
from environment variables.

Validation of the configuration can only be performed after all of the
sources have been queried, in particular because configuration files may
be specified on the command line.

The stages in processing command line arguments and configuration files
are

1.  parsing the command line

2.  parsing configuration files

3.  merging default values, values from configuration files, values from
    the command line and values from the environment.

4.  validation of configuration values.

This module concerns itself with the first three stages, and uses
CXC::Form::Tiny::Plugin::OptArgs2 to generate the command line
specifications for feeding OptArgs2 and for the last stage, validation.

  USAGE

  Command class hierarchy

OptArgs2 maps nested commands onto class hierarchies. An application
provides a single command which may have multiple nested sub-commands,
each of which must reside in a nested class below their parent command
or subcommand.

For example, if an application is called "App::demo", running it as

  % demo

will result in a call to

  [???]::demo->new(...)->run;

and running a subcommand

  % demo foo

will result in a call to

  [???]demo::foo->new(...)->run;

and so on. It doesn't matter what class "[???]" is named, or where in
the hierarchy the code is, just that it be properly nested and that the
final component in the class implementing the top-level command is the
name of the executable.

When specifying commands and subcommands to CXC::Form::Tiny::OptArgs2,
you can specify paths relative to a root class, (unlike OptArgs2, which
requires full qualified class names).

The common root, which is the name of the class which would implement
the top-level command, may be passed either to the constructor (via the
"command_class" option) or as the first argument to the "cmd" method.
=head1 EXAMPLES

   Reading configuration files

The "read_config" class method must be overridden. Here's an example
which uses YAML::PP and Path::Tiny:

  sub read_config ( $class, $file ) {
      require Path::Tiny;
      $file = Path::Tiny::path($file);
      $file->exists or die( "configuration file '$file' doesn't exist" );

      require YAML::PP;
      my $yp = YAML::PP->new( schema => [qw/ + Merge Include /] );
      return $yp->load_string( $file->slurp_utf8 );
  }

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023 by Smithsonian Astrophysical
Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007