view release on metacpan or  search on metacpan

docs/Ext.txt  view on Meta::CPAN

                        return $a + $b; # or equally WRONG:
                        return '"' . ($a + $b) . '"''; 
                }

        You should not perform the operation in compilation time, but enable
        it to perform in run time. The second version will work for
        <$RPLUS.4.5> but NOT for <$RPLUS.5.<$RVAR.a>>, which will result in
        a hard coded zero.

IMPLEMENTING VARIOUS TAGS
    Functions should be in all uppercase, and consist of a prefix describing
    the type of the tag, an underscore, and the tag name. Merge is case
    insensitive, so don't try to define tags with lowercase names.

            For a non block tag, use the prefix B<API>.
            For a block opening tag, use the prefix B<OAPI>.
            For a block ending tag, use the prefix B<CAPI>.
            For an output tag, use the prefix B<OUT>.

    You can use the perl functions setvar, getvar and incvar to manipulate
    Merge variables.

    Here are some examples:

            sub OAPI_CSV ($) {
                    my $filename = shift;
                    $filename =~ s/^\\(["'])(.*)\\\1$/$2/; # Drop the quotes
                                                    # in compilation time!
                    <<EOM;
                    open(I, "$filename"); # Must use double quotes!
                    local (\$__headers) = scalar(<I>); # Do not use my() ! 
                    chop \$__headers;
                    local (\@__fields) = split(/,\\s*/, \$__headers);
                    # Notice that we must escape variable names with backslashes
                    while (<I>) {
                            chop;
                            my \@__data = split(/,\\s*/);
                            foreach my \$i (0 .. \$#__fields) {
                                    setvar(\$__fields[\$i], \$__data[\$i]);
                            }
            EOM
            }

            sub CAPI_CSV () {
                    "}";
            }

            Here is how we would use it:

            <$RCSV.'/data/<$RVAR.name>'>
                    <$RVAR.worker> has salary <$RVAR.salary><BR>
            </$RCSV>

            name could be 'workers.dat', and the file /data/workers.dat could be:

            worker, salary, office
            Bill, 9999999999999, Redmond
            George, 0, White House

MACRO TAGS
    Macro tags define a tag by simply grouping merge code to be susbtituted
    under it. Suppose we have two tags, <$RFIRST> that takes two parameters,
    and <$RSECOND> that takes two as well, we could define the tag
    <$RCOMBINED> this way:

            sub MACRO_COMBINED ($$$) {
                    <<'EOM';
            First $1 and $2: <$RFIRST.$1.$2><BR>
            Second $2 and $3: <$RSECOND.$2.$3><BR>
            EOM
            }

    This tag can now be called with three parameters. Note: You do not need
    to parse the parameters yourself in a Macro tag. You need to return a
    string containing Merge code and references to the parameters like in a
    shell script. Writing a prototype is still mandatory.

DESCRIBED TAGS
    Until now, extension tags could be called only with a list of parameters
    separated by commas. But merge enables defining tags that take a syntax
    similar to Merge native tags.

    Suppose we define a tag:

            sub OUT_MINUS ($$) {
                    my ($a, $b) = @_;
                    qq!("$a") - ("$b")!;
            }

    Now suppose we define a description function:

            sub DESC_MINUS {
                    'U-U';
            }

    We can now call the new tag: <$RMINUS.7-6> or <$RMINUS.<$RVAR.x>-1> and
    so on.

    All the non alpha characters in the description string stand for
    themselves. The following letters are assigned:

            U - Unquoted parameters (e.g. 9, ball, <$RVAR.a> etc).
            Q - Quote parameter, (e.g. 'building', "quoted string", 'a "parameter" with <$RVAR.a> inside')
            E - Call can end here, rest of the parameters optional. For example, a tag with the description QE:Q-QE*Q can be called as either 'first', 'first':'second'-'third' or 'first':'second'-'third'*'fourth'.
            D - Either a dot or equal sign.

MOD PERL COMPLIANCE NOTICE
    Merge implements the extensions by compiling them as Perl code into
    Merge itself. Therefore, on a mod_perl driven web server with several
    instances, extensions will be shared among all instances.

COPYRIGHT
    Copyright (c) 1999 - 2005 Raz Information Systems Ltd.
    http://www.raz.co.il

    This package is distributed under the same terms as Perl itself, see the
    Artistic License on Perl's home page.