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 loaded rc file or module.

MODULE

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

Following initialize, function defined with module option is called.

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

FILE

As for rc file, section after __PERL__ mark is executed as Perl program. At this time, module object is assigned to variable $MODULE, and you can access 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 shellwords routine defined in Text::ParseWords module. Be sure that this module sometimes requires escape backslashes.

Any kind of string can be used for 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 to include following arguments within replaced strings, two special notations can be used in option definition.

String $<n> is replaced by the nth argument after the substituted option, where n is number start from one. Because $<0> is replaced by the defined option itself, you have to care about infinite loop.

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

For example, when

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

is defined, command

greple --line 10,20-30,40

will be evaluated as this:

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

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

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

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

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

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

expand name string

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

This is similar to string macro defined by following define command. But macro expantion is done by simple string replacement, so you have to use expand to define option composed by multiple arguments.

define name string

Define string macro. This is similar to option, but argument is not processed by shellwords and treated just a simple text, so meta-characters can be included without escape. Macro expansion is done for option definition and other macro definition. Macro is not evaluated in command line option. Use option directive if you want to use in command line,

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

Here-document can be used to define string inluding newlines.

define __script__ <<EOS
{
	...
}  
EOS

Special macro __PACKAGE__ is pre-defined to module name.

help name

Define help message for option name.

builtin spec variable

Define built-in option which should be processed by option parser. Defined option spec can be taken by builtin method, and script is responsible to give them to parser.

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

autoload module options

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

For example,

autoload -Mdig --dig

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

mode [no]name

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

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

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

METHODS

new configure option

Create object. Parameters are just passed to configure method.

configure

Configure object. Parameter is 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 option. Takes option name and return it's definition if available. It doesn't return default option, get it by default method.

default

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

builtin

Get built-in options.

autoload

Set autoload module.

mode

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

mode(function => 1)

Interpret the argument start with '&' as a function, and replace it by the result of the function call.

mode(wildcard => 1)

Replace wildcard argument by matched file names.