Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
App::Yath::Options(3) User Contributed Perl DocumentationApp::Yath::Options(3)

NAME
       App::Yath::Options - Tools for defining and tracking yath CLI options.

DESCRIPTION
       This class represents a collection of options, and holds	the logic for
       processing them.	This package also exports sugar	to help	you define
       options.

SYNOPSIS
	   package My::Options;

	   use App::Yath::Options;

	   # This package now has a package instance of	options, which can be obtained
	   # via the options() method.
	   my $options = __PACKAGE__->options;

	   # We	can include options from other packages
	   include_options(
	       'Package::With::Options::A',
	       'Package::With::Options::B',
	       ...,
	   );

	   # Define an option group with some options
	   option_group	{ %common_fields } => sub {

	       # Define	an option
	       option foo => (
		   type	=> 's',
		   default => "FOOOOOOO",
		   category => 'foo',
		   description => "This	is foo"
		   long_examples => [' value'],
		   ...
	       );

	       option bar => ( ... );
	       ...
	   };

	   # Action to call right after	options	are parsed.
	   post	sub {
	       my %params = @_;

	       ...
	   };

EXPORTS
       $opts = options()
       $opts = $class->options()
	   This	returns	the options instance associated	with your package.

       include_options(@CLASSES)
	   This	lets you include options defined in other packages.

       option_group \%COMMON_FIELDS => sub { ... }
	   An option group is simply a block where all calls to	"option()"
	   will	have common fields added automatically,	this makes it easier
	   to define multiple options that share common	fields.	Common fields
	   can be overridden inside the	option definition.

	   These are both equivelent:

	       # Using option group
	       option_group { category => 'foo', prefix	=> 'foo' } => sub {
		   option a => (type =>	'b');
		   option b => (type =>	's');
	       };

	       # Not using option group
	       option a	=> (type => 'b', category => 'foo', prefix => 'foo');
	       option b	=> (type => 's', category => 'foo', prefix => 'foo');

       option TITLE => %FIELDS
	   Define an option. The first argument	is the "title" attribute for
	   the new option, all other arguments should be attribute/value pairs
	   used	to construct the option. See App::Yath::Option for the
	   documentation of attributes.

       post sub	{ ... }
       post $weight => sub { ... }
	   "post" callbacks are	run after all command line arguments have been
	   processed.  This is a place to verify the result of several options
	   combined, sanity check, or even add short-circuit behavior. This is
	   how the "--help" and	"--show-opts" options are implemented.

	   If no $weight is specified then 0 is	used. "post" callbacks or
	   sorted based	on weight with higher values being run later.

OPTIONS	INSTANCES
       In general you should not be using the options instance directly.
       Options instances are mostly an implementation detail that should be
       treated as a black box. There are however a few valid reasons to
       interact	with them directly. In those cases there are a few public
       attributes/methods you can work with. This section documents the	public
       interface.

   ATTRIBUTES
       This section only lists attributes that may be useful to	people working
       with options instances. There are a lot of internal (to yath)
       attributes that are implementation details that are not listed here.
       Attributes not listed here are not intended for external	use and	may
       change at any time.

       $arrayref = $options->all
	   Arrayref containing all the App::Yath::Option instances in the
	   options instance.

       $settings = $options->settings
	   Get the Test2::Harness::Settings instance.

       $arrayref = $options->args
	   Get the reference to	the list of command line arguments. This list
	   is modified as arguments are	processed, there are no	guarentees
	   about what is in here at any	given stage of argument	processing.

       $class_name = $options->command_class
	   If yath has determined what command is being	executed this will be
	   populated with that command class. This will	be undefined if	the
	   class has not been determined yet.

       $arrayref = $options->used_plugins
	   This	is a list of all plugins who's options have been used. Plugins
	   may appear more than	once.

       $hashref	= $options->included
	   A hashref where every key is	a package who's	options	have been
	   included into this options instance.	The values are an
	   implementation detail, do not rely on them.

   METHODS
       This section only lists methods that may	be useful to people working
       with options instances. There are a lot of internal (to yath) methods
       that are	implementation details that are	not listed here. Methods not
       listed here are not intended for	external use and may change at any
       time.

       $opt = $options->option(%OPTION_ATTRIBUTES)
	   This	will create a new option with the provided attributes and add
	   it to the options instance. A "trace" attribute will	be
	   automatically set for you.

       $options->include($options_instance)
	   This	method lets you	directly include options from a	second
	   instance into the first.

       $options->include_from(@CLASSES)
	   This	lets you include options from multiple classes that have
	   options defined.

       $options->include_option($opt)
	   This	lets you include a single already defined option instance.

       $options->pre_docs($format, @args)
	   Get documentation for pre-command options. $format may be 'cli' or
	   'pod'.

       $options->cmd_docs($format, @args)
	   Get documentation for command options. $format may be 'cli' or
	   'pod'.

SOURCE
       The source code repository for Test2-Harness can	be found at
       http://github.com/Test-More/Test2-Harness/.

MAINTAINERS
       Chad Granum <exodist@cpan.org>

AUTHORS
       Chad Granum <exodist@cpan.org>

COPYRIGHT
       Copyright 2020 Chad Granum <exodist7@gmail.com>.

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

       See http://dev.perl.org/licenses/

perl v5.32.0			  2020-08-24		 App::Yath::Options(3)

NAME | DESCRIPTION | SYNOPSIS | EXPORTS | OPTIONS INSTANCES | SOURCE | MAINTAINERS | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=App::Yath::Options&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help