view release on metacpan or  search on metacpan

docs/Ext.html  view on Meta::CPAN

        }</pre>
<p>You should not perform the operation in compilation time, but enable it to
perform in run time. The second version will work for
&lt;$RPLUS.4.5&gt; but <strong>NOT</strong> for &lt;$RPLUS.5.&lt;$RVAR.a&gt;&gt;, which will result in a
hard coded zero.</p>
<p></p></ol>
<p>
</p>
<hr />
<h1><a name="implementing_various_tags">IMPLEMENTING VARIOUS TAGS</a></h1>
<p>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.</p>
<pre>
        For a non block tag, use the prefix B&lt;API&gt;.
        For a block opening tag, use the prefix B&lt;OAPI&gt;.
        For a block ending tag, use the prefix B&lt;CAPI&gt;.
        For an output tag, use the prefix B&lt;OUT&gt;.</pre>
<p>You can use the perl functions setvar, getvar and incvar to manipulate Merge
variables.</p>
<p>Here are some examples:</p>
<pre>
        sub OAPI_CSV ($) {
                my $filename = shift;
                $filename =~ s/^\\([&quot;'])(.*)\\\1$/$2/; # Drop the quotes
                                                # in compilation time!
                &lt;&lt;EOM;
                open(I, &quot;$filename&quot;); # Must use double quotes!
                local (\$__headers) = scalar(&lt;I&gt;); # Do not use my() ! 
                chop \$__headers;
                local (\@__fields) = split(/,\\s*/, \$__headers);
                # Notice that we must escape variable names with backslashes
                while (&lt;I&gt;) {
                        chop;
                        my \@__data = split(/,\\s*/);
                        foreach my \$i (0 .. \$#__fields) {
                                setvar(\$__fields[\$i], \$__data[\$i]);
                        }
        EOM
        }</pre>
<pre>
        sub CAPI_CSV () {
                &quot;}&quot;;
        }</pre>
<pre>
        Here is how we would use it:</pre>
<pre>
        &lt;$RCSV.'/data/&lt;$RVAR.name&gt;'&gt;
                &lt;$RVAR.worker&gt; has salary &lt;$RVAR.salary&gt;&lt;BR&gt;
        &lt;/$RCSV&gt;</pre>
<pre>
        name could be 'workers.dat', and the file /data/workers.dat could be:</pre>
<pre>
        worker, salary, office
        Bill, 9999999999999, Redmond
        George, 0, White House</pre>
<p>
</p>
<hr />
<h1><a name="macro_tags">MACRO TAGS</a></h1>
<p>Macro tags define a tag by simply grouping merge code to be susbtituted under 
it. Suppose we have two tags, &lt;$RFIRST&gt; that takes two parameters, and 
&lt;$RSECOND&gt; that takes two as well, we could define the tag &lt;$RCOMBINED&gt;
this way:</p>
<pre>
        sub MACRO_COMBINED ($$$) {
                &lt;&lt;'EOM';
        First $1 and $2: &lt;$RFIRST.$1.$2&gt;&lt;BR&gt;
        Second $2 and $3: &lt;$RSECOND.$2.$3&gt;&lt;BR&gt;
        EOM
        }</pre>
<p>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.</p>
<p>
</p>
<hr />
<h1><a name="described_tags">DESCRIBED TAGS</a></h1>
<p>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.</p>
<p>Suppose we define a tag:</p>
<pre>
        sub OUT_MINUS ($$) {
                my ($a, $b) = @_;
                qq!(&quot;$a&quot;) - (&quot;$b&quot;)!;
        }</pre>
<p>Now suppose we define a description function:</p>
<pre>
        sub DESC_MINUS {
                'U-U';
        }</pre>
<p>We can now call the new tag: &lt;$RMINUS.7-6&gt; or &lt;$RMINUS.&lt;$RVAR.x&gt;-1&gt;
and so on.</p>
<p>All the non alpha characters in the description string stand for themselves.
The following letters are assigned:</p>
<pre>
        U - Unquoted parameters (e.g. 9, ball, &lt;$RVAR.a&gt; etc).
        Q - Quote parameter, (e.g. 'building', &quot;quoted string&quot;, 'a &quot;parameter&quot; with &lt;$RVAR.a&gt; 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.</pre>
<p>
</p>
<hr />
<h1><a name="mod_perl_compliance_notice">MOD PERL COMPLIANCE NOTICE</a></h1>
<p>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.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (c) 1999 - 2005 Raz Information Systems Ltd.
<a href="http://www.raz.co.il">http://www.raz.co.il</a></p>
<p>This package is distributed under the same terms as Perl itself, see the
Artistic License on Perl's home page.</p>

</body>

</html>