I have been promising to give an update on what is going on with the
parser, so here it is. Forgive any goofy spelling and grammar - I am
beat - and if there is anything useful here, I am sure Minister of
Documentation John Castura will make it spiffy.
The two biggest changes recently beside bug fixes are motived by the
idea that Velocity is a general purpose template engine (not just for
outputting HTML), and therefore we have to be very careful that the
output is both predictable and doesn't damage the non-VTL components of
the input templates (called hereafter, 'schmoo').
Escape Handling
----------------
The escape handling rules are very simple now.
1) When a non-null reference (a reference that refers to actual data in
the Context) is preceeded by a '\', it will be rendered as $<reference>.
2) When a VTL directive ( #if, #else, #elseif, #end, #set, #foreach ...)
is preceeded by a '\', it will be rendered as #<directive>.
3) In any other case, the '\' has no effect, and is simply output as-is.
This means:
#set $foo = "woogie"
\$foo => $foo
\$bar => $bar
would output as :
$foo => woogie
\$bar => $bar
because $bar is not a reference (assuming in this case that there is no
data element 'bar' in the Context).
Further
\#foreach(
\#whumpus
would render as
#foreach(
\#whumpus
because foreach() is a valid directive, and currently, whumpus isn't.
I hope you get the idea. See test/templates/test.vm and escape.vm for
more examples.
'What You Expect'
-----------------
Don't know what else to call this. Maybe 'What You Want'. The basic
idea is that the VTL (Velocity Template Language) control structures
such as #if, #end, etc. should not render anything into the output
stream. This allows precise output control for those generating output
where whitespace and newlines matter. For most of us, our output is
HTML and Java, both being rather tolerant of spurious whitespace, so it
doesn't matter. But if you want to use Vel for something else, like
automated text output, it does matter.
Below, when I say 'inline' I mean 'in the schmoo stream' -> you don't
have to start on a new line.
The basic rules :
1) #set will eat all preceeding whitespace and any following whitespace,
including the newline, which is mandatory. It should not (cannot?) be
used inline. There will be another #set statement (#inlineset() ?) for
inline use offered soon for any masochists who insist on using #set
inline.
2) All other directives leave preceeding whitespace alone to respect
'What You Expect' and eat any trailing whitespace if they are followed
by a newline. If the whitespace is not followed immediately by a
newline, the whitespace is rendered.
I think that's it.
So, let me show with some examples.
input to show how the directives render to nothing:
---
#if(false)
$foo
#end
---
output:
---
---
input to demonstrate inlining a #foreach() :
---
#set $colors =["red", "blue", "tangerine"]
>#foreach($color in $colors)$color #end<
---
output:
---
>red blue tangerine <
---
input - remove the '<' at the end and see what happens when the #end
eats the newline :
---
#set $colors =["red", "blue", "tangerine"]
>#foreach($color in $colors)$color #end
---
output :
---
>red blue tangerine ---
See? since there was no newline after $color in the block, the --- was
sucked right up to the space trailing the last color. This is as
expected because the #end ate the newline. 'Ate' is official parser
jargon. :)
How about an inline #if() to make nice text output:
----
#set $foo = "bar"
\$foo is a#if($foo) valid#else not defined#end VTL reference.
\$bar is a#if($bar) valid#else not defined#end VTL reference.
---
output:
----
$foo is a valid VTL reference.
\$bar is a not defined VTL reference.
---
The point is, you can tuck the VTL control structures now pretty much
wherever you want, the output should be What You Expect. For more
examples, see test/templates/pedantic.vm
Hope this clears things up a little, and hope the fixes are what people
want. Comments and suggestions not only welcome, but expected.
geir
--
Geir Magnusson Jr. [EMAIL PROTECTED]
Dakota tribal wisdom: "when you discover you are riding a dead horse,
the best strategy is to dismount."
