[ The Sunny Spot ] WPP v2.13 - The Web Preprocessor
Author : Marco Lamberto
Preprocessed by WPP
   Index < Previous    Next >   

  Macro expansion [ ^ ]

@MACRO MNAME(arg1, arg2, ...)@
   ...
@ENDMACRO@
Declare MNAME as a new macro. Notice that the valid charset for the name and the arguments is the same of the variables (A-Z,0-9,_).

@MNAME("arg1", "arg2", ...)@

Calls MNAME. Notice that the " are required only if you are using string constants as argument, you can omit them if you use a variable (with the @ included). If you use " into a macro argument you should excape it with a \.

Source file
<!-- macro declaration -->
@MACRO MY_MACRO(NAME, HREF)@
<A HREF="@HREF@">@NAME@</A>
@ENDMACRO@

<!-- macro called with args containing string constants -->
@MY_MACRO("Test", "test.html")@

<!-- macro called with args containing variables -->
@MY_MACRO(@FILENAME@, "@FILENAME@.html")@

<!-- example of splitted macro call -->
@MY_MACRO("\"@FILENAME@\" is the source",\
    "@FILENAME@.html")@

Notes

  • You cannot declare a macro from inside another macro.
  • Macros can be called within other macros (pay attention to recursive calls!), variables assignments or macro aguments.

  Built-in macros [ ^ ]

Built-in macros are predefined macros allowing particular operations, you can use them as normal macros.
Usually if a built-in macro reads data from a file, this file will be included into the dependencies list (see the --depend switch).

Macros working on images

Allowed file formats are GIF, JPEG and PNG.

Macro Expanded to
@HTML_IMAGE(img)@ <IMG SRC="img" WIDTH="(image width)" HEIGHT="(image height)">
@HTML_IMAGE(img, alt)@ <IMG SRC="img" WIDTH="(image width)" HEIGHT="(image height)" ALT="alt" >
@HTML_IMAGE(img, alt, extra)@ <IMG SRC="img" WIDTH="(image width)" HEIGHT="(image height)" ALT="alt" extra>
@HTML_IMAGE_SIZE(img)@ SRC="img" WIDTH="(image width)" HEIGHT="(image height)"
@HTML_IMAGE_SIZEO(img)@ WIDTH="(image width)" HEIGHT="(image height)"
@HTML_IMAGE_WIDTH(img)@ WIDTH="(image width)"
@HTML_IMAGE_HEIGHT(img)@ HEIGHT="(image height)"
@IMAGE_WIDTH(img)@ (image width)
@IMAGE_HEIGHT(img)@ (image height)

Example:

Source file
@HTML_IMAGE("index.jpg", "my logo",\
    "BORDER=0 HSPACE=10")@
HTML file
<IMG SRC="index.jpg" WIDTH=100 HEIGHT=200 ALT="my logo" BORDER=0 HSPACE=10 >

Macros working on image maps

These macros read a server side imagemap and are expanded into a converted HTML client side version.
In the map files the ALT field is taken from the comment line before the area definition.

Macro Expanded to
@CERN2HTML(mapfile)@
@NCSA2HTML(mapfile)@
<MAP NAME="mapfile">
<AREA SHAPE="..." HREF="..." COORDS="..." ALT="...">
</MAP>
@CERN2HTML(mapfile, mapname)@
@NCSA2HTML(mapfile, mapname)@
<MAP NAME="mapname">
<AREA SHAPE="..." HREF="..." COORDS="..." ALT="...">
</MAP>

Example:

Source file
@NCSA2HTML("index.map", "myindex")@

<A HREF="index.map"><IMG SRC="menu.gif" WIDTH=600 HEIGHT=50
    ISMAP USEMAP="#myindex"></A>

Macros working on files

Macro Expanded to
@FILE_SIZE(file)@ (file size in bytes)
@FILE_DATE(file)@ (file modification date, according to DATE_FORMAT)

Misc macros

Macro Expanded to
@SYSTEM(cmd)@ (cmd output)
@RANDOM()@ Random integer value taken from Perl's rand() value without the leading '0.'
@RANDOM(to)@ Random integer value starting from 0 up to to
@RANDOM(from, to)@ Random integer value starting from from up to to

  The EVAL macro [ ^ ]

The EVAL macro was added in order to allow more sophisticated expansions and it was a way for adding loops and complex controls without implementing them directly (yeah, I'm a lazy boy!).
The argument string should be a valid Perl expression, otherwise wpp will warn you of syntax errors without stopping the parsing process.

Macro Expanded to
@EVAL(expr)@ (the output of the Perl expression expr)

The following example shows a simple for loop (in Perl), it outputs a sequence of numbers starting from 0 up to 10. Please notice how the '"' char should be still escaped throgh '\"'.

@EVAL(" \
	for($i = 0, $str = ''; $i < 11; $i++) { \
		$str .= $i . ' '; \
	} \
	return $str; \
")@

The string passed as argument to the EVAL macro can contain wpp variables and macros, they will be expanded before evaluation through Perl's eval.

@LIMIT=11@
@EVAL(" \
	for($i = 0, $str = ''; $i < @LIMIT@; $i++) { \
		$str .= \"@RANDOM()@ \"; \
	} \
	return $str; \
")@

If you run the previous example you can notice that the RANDOM() output is always the same, that's because the evaluation of RANDOM() is done before the eval call.
Within a evaluated string you could call wpp parser by using the function wpp_eval, which takes a string as input argument and returns the parsed string.
In the following example I've modified the previous one in order to call wpp_eval. Please notice the "'@'.'RANDOM()@'", I've splitted the the RANDOM() call in order to avoid it's parsing before eval, so I've used the perl string concatenation operator '.' for rebuilding the right call at evaluation time.

@EVAL(" \
	for($i = 0, $str = ''; $i < @LIMIT@; $i++) { \
		$str .= wpp_eval('@'.'RANDOM()@') . ' '; \
	} \
	return $str; \
")@

This is a bit more complex example, here I open and read a file (/etc/group), for each line of it I call the macro TEST that simply print it within square brackets.

@MACRO TEST(TEXT)@
	[@TEXT@]
@ENDMACRO@

@F=/etc/group@

@EVAL(" \
	$str = ''; \
	open(FH, '@F@'); \
	while (<FH>) { \
		chomp; \
		$str .= wpp_eval('@TEST(\"'.$_.'\")@') . \"\n\"; \
	}; \
	close(FH); \
	return $str; \
")@

Here you can see how to use EVAL for test conditions.

@TVAL=@EVAL("1 != 1")@@
@IF !TVAL@
	EVAL ok!
@ENDIF@

@TVAL=@EVAL("1 == 1")@@
@IF TVAL@
	EVAL ok!
@ENDIF@

EVAL returns the value returned by the Perl expression, however if you don't want return a value, just because you've already done it with a print or something similar inside the Perl expression, you have to return explicitly an empty string (tipically a "return '';"). Note that the print statement could be effectively printed before the text preceding the EVAL call, that's because WPP buffers its output, so don't use print or printf, instead output data within a string and return it at the end of the computation process.
The second line of the example shows a safer way for outputing data.

@EVAL("print 'TEST ' . (1 == 1); return '';")@

@EVAL("return 'TEST ' . (1 == 1);")@

The following and last example shows an invalid expression that raise an EVAL error, the parsing doesn't stop but a warning is printed by WPP.

@EVAL("1+1'A'")@

   ^ Top < Previous    Next >   
Marco (LM) Lamberto lm@geocities.com
Revised: 2000/12/10 17:45:30
http://www.geocities.com/Tokyo/1474/wpp/manual_6.html
Preprocessed by WPP Graphics by GIMP