NAME

Getopt::EX::Module - RC/Module data container

SYNOPSIS

  use Getopt::EX::Module;

  my $bucket = Getopt::EX::Module->new(
	BASECLASS => $baseclass,
	FILE => $file_name  /  MODULE => $module_name,
	);

DESCRIPTION

This module is usually used from Getopt::EX::Loader, and keeps all data about the loaded rc file or module.

MODULE

After a user-defined module is loaded, the subroutine initialize is called if it exists in the module. At this time, the container object is passed to the function as the first argument and the following command argument pointer as the second. So you can use it to directly access the object contents through the class interface.

Following initialize, the function defined with the module option is called.

Finally, the subroutine finalize is called if defined, to finalize the startup process of the module.

FILE

For rc files, the section after the __PERL__ or __PERL5__ mark is executed as a Perl program. At this time, the module object is assigned to the variable $MODULE, and you can access the module API through it.

if (our $MODULE) {
    $MODULE->setopt('default', '--number');
}

RC FILE FORMAT

option name string

Define option name. Argument string is processed by the shellwords routine defined in the Text::ParseWords module. Be aware that this module sometimes requires escaped backslashes.

Any kind of string can be used for an option name but it is not combined with other options.

option --fromcode --outside='(?s)\/\*.*?\*\/'
option --fromcomment --inside='(?s)\/\*.*?\*\/'

If the option named default is defined, it will be used as a default option.

For the purpose of including following arguments within replaced strings, two special notations can be used in option definitions.

The string $<n> is replaced by the nth argument after the substituted option, where n is a number starting from one. Because $<0> is replaced by the defined option itself, you have to be careful about infinite loops.

The string $<shift> is replaced by the following command line argument and the argument is removed from the list.

For example, when

option --line --le &line=$<shift>

is defined, the command

greple --line 10,20-30,40

will be evaluated as:

greple --le &line=10,20-30,40

There are special arguments to manipulate option behavior and the rest of the arguments. Argument $<move> moves all following arguments there, $<remove> just removes them, and $<copy> copies them. These do not work when included as part of a string.

They take one or two optional parameters, which are passed to the Perl splice function as offset and length. $<move(0,1)> is the same as $<shift>; $<copy(0,1)> is the same as $<1>; $<move> is the same as $<move(0)>; $<move(-1)> moves the last argument; $move(1,1) moves the second argument. The next example exchanges the following two arguments.

option --exch $<move(1,1)>

You can use the recently introduced $<ignore> to ignore the argument. Some existing modules use $<move(0,0)> for the same purpose, because it effectively does nothing.

option --deprecated $<ignore>
option --deprecated $<move(0,0)>

expand name string

Define local option name. The expand command is almost the same as the option command in terms of its function. However, options defined by this command are expanded in, and only in, the process of definition, while option definitions are expanded when command arguments are processed.

This is similar to a string macro defined by the following define command. But macro expansion is done by simple string replacement, so you have to use expand to define options composed of multiple arguments.

define name string

Define a string macro. This is similar to option, but the argument is not processed by shellwords and is treated as simple text, so meta-characters can be included without escaping. Macro expansion is performed for option definitions and other macro definitions. Macros are not evaluated in command line options. Use the option directive if you want to use it in the command line,

define (#kana) \p{InKatakana}
option --kanalist --nocolor -o --join --re '(#kana)+(\n(#kana)+)*'
help   --kanalist List up Katakana string

A here-document can be used to define strings including newlines.

define __script__ <<EOS
{
	...
}  
EOS

The special macro __PACKAGE__ is pre-defined to the module name.

help name

Define a help message for option name.

builtin spec variable

Define a built-in option which should be processed by the option parser. The defined option spec can be retrieved by the builtin method, and the script is responsible for passing them to the parser.

Arguments are assumed to be Getopt::Long style specs, and variable is a string starting with $, @ or %. They will be replaced by a reference to the object which the string represents.

autoload module options

Define a module which should be loaded automatically when the specified option is found in the command arguments.

For example,

autoload -Mdig --dig

replaces the option "--dig" with "-Mdig --dig", and the dig module is loaded before processing the --dig option.

mode [no]name

Set or unset mode name. Currently, function and wildcard can be used as a name. See the METHODS section.

The next example is used in the App::Greple::subst::dyncmap module to produce parameters on the fly.

mode function
option --dyncmap &dyncmap($<shift>)

METHODS

new configure option

Create an object. Parameters are passed to the configure method.

configure

Configure the object. Parameters are passed in hash name and value style.

BASECLASS => class

Set base class.

FILE => filename

Load file.

MODULE => modulename

Load module.

define name, macro

Define macro.

setopt name, option

Set option.

setlocal name, option

Set option which is effective only in the module.

getopt name

Get an option. Takes an option name and returns its definition if available. It doesn't return the default option; get it by the default method.

default

Get the default option. Use setopt(default => ...) to set it.

builtin

Get built-in options.

autoload

Set autoload module.

mode

Set the argument treatment mode. Arguments produced by option expansion will be the subject of post-processing. This method defines the behavior of it.

mode(function => 1)

Interpret arguments starting with '&' as a function, and replace them with the result of the function call.

mode(wildcard => 1)

Replace wildcard arguments with matched file names.