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

FreeBSD Manual Pages

  
 
  

home | help
Getopt::Compact::WithCUser)Contributed Perl DocumenGetopt::Compact::WithCmd(3)

NAME
       Getopt::Compact::WithCmd	- sub-command friendly,	like Getopt::Compact

SYNOPSIS
       inside foo.pl:

	 use Getopt::Compact::WithCmd;

	 my $go	= Getopt::Compact::WithCmd->new(
	    name	  => 'foo',
	    version	  => '0.1',
	    args	  => 'FILE',
	    global_struct => [
	       [ [qw/f force/],	'force overwrite', '!',	\my $force ],
	    ],
	    command_struct => {
	       get => {
		   options     => [
		       [ [qw/d dir/], 'dest dir', '=s',	undef, { default => '.'	} ],
		       [ [qw/o output/], 'output file name', '=s', undef, { required =>	1 }],
		   ],
		   desc	       => 'get file from url',
		   args	       => 'url',
		   other_usage => 'blah	blah blah',
	       },
	       remove => {
		   ...
	       }
	    },
	 );

	 my $opts = $go->opts;
	 my $cmd  = $go->command;

	 if ($cmd eq 'get') {
	     my	$url = shift @ARGV;
	 }

       how will	be like	this:

	 $ ./foo.pl -f get -o bar.html http://example.com/

       usage, running the command './foo.pl -x'	results	in the following
       output:

	 $ ./foo.pl -x
	 Unknown option: x
	 foo v0.1
	 usage:	foo.pl [options] COMMAND FILE

	 options:
	    -h,	--help		 This help message
	    -f,	--force	  Bool	 Force overwrite

	 Implemented commands are:
	    get	  Get file from	url

	 See 'foo.pl help COMMAND' for more information	on a specific command.

       in addition, running the	command	'./foo.pl get' results in the
       following output:

	 $ ./foo.pl get
	 `--output` option must	be specified
	 foo v0.1
	 usage:	foo.pl get [options] url

	 options:
	    -h,	--help					   This	help message
	    -d,	--dir	   Str		  (default: '.')   Dest	dir
	    -o,	--output   Str (required)		   Output file name

	 blah blah blah

DESCRIPTION
       Getopt::Compact::WithCmd	is yet another Getopt::* module.  This module
       is respected Getopt::Compact.  This module is you can define of git-
       like option.  In	addition, usage	can be set at the same time.

METHODS
   new(%args)
       Create an object.  The option most Getopt::Compact compatible.  But
       struct is cannot	use.

       The new %args are:

       "global_struct($arrayref)"
	   This	option is sets common options across commands.	This option
	   value is Getopt::Compact compatible.	 In addition, extended to
	   other values	can be set.

	     use Getopt::Compact::WithCmd;
	     my	$go = Getopt::Compact::WithCmd->new(
		 global_struct => [
		     [ $name_spec_arrayref, $description_scalar, $argument_spec_scalar,	\$destination_scalar, $opt_hashref ],
		     [ ... ]
		 ],
	     );

	   And you can also write in hash style.

	     use Getopt::Compact::WithCmd;
	     my	$go = Getopt::Compact::WithCmd->new(
		 global_struct => {
		     $name_scalar => {
			 alias => $name_spec_arrayref,
			 desc  => $description_scalar,
			 type  => $argument_spec_scalar,
			 dest  => \$destination_scalar,
			 opts  => $opt_hashref,
		     },
		     $other_name_scalar	=> {
			 ...
		     },
		 },
	     );

	   $argument_spec_scalar can be	set value are Getopt::Long's option
	   specifications.  And	you can	also specify the following readable
	   style:

	     Bool     #	eq !
	     Incr     #	eq +
	     Str      #	eq =s
	     Int      #	eq =i
	     Num      #	eq =f
	     ExNum    #	eq =o

	   In addition,	Array and Hash type are:

	     Array[Str]	# eq =s@
	     Hash[Int]	# eq =i%
	     ...

	   $opt_hasref are:

	     {
		 default  => $value, # default value
		 required => $bool,
	     }

       "command_struct($hashref)"
	   This	option is sets sub-command and options.

	     use Getopt::Compact::WithCmd;
	     my	$go = Getopt::Compact::WithCmd->new(
		 command_struct	=> {
		     $command => {
			 options	=> $options,
			 args		=> $args,
			 desc		=> $description,
			 other_usage	=> $other_usage,
			 command_struct	=> $command_struct,
		     },
		 },
	     );

	   $options

	   This	value is compatible to "global_struct".

	   $args

	   command args.

	   $description

	   command description.

	   $other_usage

	   other usage message.	 be added to the end of	the usage message.

	   $command_struct

	   support nesting.

	     use Getopt::Compact::WithCmd;
	     my	$go = Getopt::Compact::WithCmd->new(
		 command_struct	=> {
		     $command => {
			 options	=> $options,
			 args		=> $args,
			 desc		=> $description,
			 other_usage	=> $other_usage,
			 command_struct	=> {
			     $sub_command => {
				 options => ...
			     },
			 },
		     },
		 },
	     );

	     # will run	cmd:
	     $ ./foo.pl	$command $sub_command ...

   add_type($new_type, $src_type, $code_ref);
       This method is additional your own type.	 You must be call before new()
       method.

	 use JSON;
	 use Data::Dumper;

	 Getopt::Compact::WithCmd->add_type(JSON => Str	=> sub { decode_json(shift) });
	 my $go	= Getopt::Compact::WithCmd->new(
	     global_struct => {
		 from_json => {
		     type => 'JSON',
		 },
	     },
	 );
	 my $data = $go->opts->{from_json};
	 print Dumper $data;

	 # will	run cmd:
	 $ ./add_type.pl --from_json '{"foo":"bar"}'
	 $VAR1 = {
		   'foo' => 'bar'
		 };

   new_from_array(\@myopts, %args);
       "new_from_array"	can be used to parse options from an arbitrary array.

	 $go = Getopt::Compact::WithCmd->new_from_array(\@myopts, ...);

   new_from_string($option_string, %args);
       "new_from_string" can be	used to	parts options from an arbitrary
       string.

       This method using Text::ParseWords on internal.

	 $go = Getopt::Compact::WithCmd->new_from_string('--foo	bar baz', ...);

   opts
       Returns a hashref of options keyed by option name.  Return value	is
       merged global options and command options.

   command
       Gets sub-command	name.

	 # inside foo.pl
	 use Getopt::Compact::WithCmd;

	 my $go	= Getopt::Compact::WithCmd->new(
	    command_struct => {
	       bar => {},
	    },
	 );

	 print "command: ", $go->command, "\n";

	 # running the command
	 $ ./foo.pl bar
	 bar

   commands
       Get sub commands. Returned value	is ARRAYREF.

	 # inside foo.pl
	 use Getopt::Compact::WithCmd;

	 my $go	= Getopt::Compact::WithCmd->new(
	    command_struct => {
	       bar => {
		   command_struct => {
		       baz => {},
		   },
	       },
	    },
	 );

	 print join(", ", @{$go->commands}), "\n";

	 # running the command
	 $ ./foo.pl bar	baz
	 bar, baz

   status
       This is a true value if the command line	was processed successfully.
       Otherwise it returns a false result.

	 $go->status ? "success" : "fail";

   is_success
       Alias of	"status"

	 $go->is_success # == $go->status

   usage
       Gets usage message.

	 my $message = $go->usage;
	 my $message = $go->usage($target_command_name); # must	be implemented command.

   show_usage
       Display usage message and exit.

	 $go->show_usage;
	 $go->show_usage($target_command_name);

   completion
       Gets shell completion string.

	 my $comp = $go->completion('bash');

       NOTICE: completion() supports only one nested level of
       "command_struct".  completion() supports	only bash.

   show_completion
       Display completion string and exit.

	 $go->show_completion('bash');

   error
       Return value is an error	message	or empty string.

	 $go->error;

   args
       Return value is array reference to any remaining	arguments.

	 $go->args # like \@ARGV

   pod2usage
       Not implemented.

AUTHOR
       xaicron <xaicron	{at} cpan.org>

COPYRIGHT
       Copyright 2010 -	xaicron

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

SEE ALSO
       Getopt::Compact

perl v5.32.1			  2021-11-04	   Getopt::Compact::WithCmd(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHOR | COPYRIGHT | LICENSE | SEE ALSO

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

home | help