view release on metacpan or  search on metacpan

lib/Getopt/EX/Module.pm  view on Meta::CPAN

strings, two special notations can be used in option definition.

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

String C<< $<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 C<< $<move> >> moves all following arguments
there, C<< $<remove> >> just removes them, and C<< $<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
C<splice> function as I<offset> and I<length>.  C<< $<move(0,1)> >> is
same as C<< $<shift> >>; C<< $<copy(0,1)> >> is same as C<< $<1> >>;
C<< $<move> >> is same as C<< $<move(0)> >>; C<< $<move(-1)> >> moves
the last argument; C<< $move(1,1) >> moves second argument.  Next
example exchange following two arguments.

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

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

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

=item B<expand> I<name> I<string>

Define local option I<name>.  Command B<expand> is almost same as
command B<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 B<define>
command.  But macro expantion is done by simple string replacement, so
you have to use B<expand> to define option composed by multiple
arguments.

=item B<define> I<name> I<string>

Define string macro.  This is similar to B<option>, but argument is
not processed by I<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 C<__PACKAGE__> is pre-defined to module name.

=item B<help> I<name>

Define help message for option I<name>.

=item B<builtin> I<spec> I<variable>

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

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

=item B<autoload> I<module> I<options>

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

For example,

    autoload -Mdig --dig

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

=item B<mode> [I<no>]I<name>

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

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

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

=back

=head1 METHODS

=over 4