NAME

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

SYNOPSIS

  use Getopt::EX::Module;
  my $bucket = new Getopt::EX::Module
        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.

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.

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 three 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 in 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)>
    

Because "$<move(0,0)>" does nothing, you can use it to ignore option.

    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.

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.

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.