On Mon, 06 Nov 2000, Geir Magnusson Jr. wrote:
> 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.
:~)
This writeup is fantastic, Geir. I'll keep an eye on this thread to see what
decisions are made.
I was thinking about the discussion re: escape characters and wondered whether
some redundancy could be useful for designers over the long run. If $foo is defined
("Gibreel") and $bar is undefined, we could have:
$foo -> Gibreel
$\foo -> $foo
$\\foo -> $\foo
$bar -> $bar
$\bar -> $bar (rather than $\bar)
$\\bar -> $\bar (rather than $\\bar)
Then, if $bar becomes a valid reference ("Saladin") in the future, no changes
would be required to the templates.
$bar -> Saladin
$\bar -> $bar
$\\bar -> $\bar
(Of course, this idea would be the same regardless of the escape
characters that are eventually decided upon.)
Anyways, I may not be thinking about this correctly, but I thought I'd throw
in my 2 cents...
Cheers,
John
> 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."
