view release on metacpan or  search on metacpan

lib/HTML/Merge/Ext.pm  view on Meta::CPAN

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 B<NOT> for <$RPLUS.5.<$RVAR.a>>, which will result in a
hard coded zero.

=back

=head1 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

=head1 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.

=head1 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.

=head1 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.


=head1 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.

=cut