svn commit: r1843797 - in /velocity/site/cms/trunk/content/engine/devel: developer-guide.mdtext user-guide.mdtext vtl-reference.mdtext

[cb...@apache.org]

Author: cbrisson
Date: Sat Oct 13 22:31:47 2018
New Revision: 1843797

URL: http://svn.apache.org/viewvc?rev=1843797&view=rev
Log:
[site/engine] Document alternate values (and other minor fixes)

Modified:
    velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
    velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
    velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext

Modified: velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext?rev=1843797&r1=1843796&r2=1843797&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Sat Oct 13 22:31:47 2018
@@ -916,6 +916,8 @@ All event handler interfaces available i
 >                                      Info info);
 >     }
 >
+> When a reference has an alternate value provided, as in `${foo.bar|'foo'}`, whenever `$foo.bar` is invalid, the invalid reference handler is called **before** the alternate value (and the alternate value will be used only if the value returned by the handler evaluates to null, false, empty or zero).
+>
 > Available implementations include:
 >
 > + `org.apache.velocity.app.event.implement.ReportInvalidReferences`

Modified: velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext?rev=1843797&r1=1843796&r2=1843797&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext Sat Oct 13 22:31:47 2018
@@ -291,6 +291,15 @@ There is ambiguity here, and Velocity as
 
 Now Velocity knows that *$vice*, not *$vicemaniac*, is the reference. Formal notation is often useful when references are directly adjacent to text in a template.
 
+## Alternate values
+
+Formal reference notations can also be used to provide an *alternate value* whenever the boolean evaluation of a reference is false.
+
+    :::velocity
+    My name is ${name|'John Doe'}
+
+If $name is null, empty, false or zero (see [Conditionals](#conditionals)), then the altername string `'John Doe'` will be displayed.
+
 ## Quiet Reference Notation
 
 When Velocity encounters an undefined reference, its normal behavior is to output the image of the reference. For example, suppose the following reference appears as part of a VTL template.
@@ -380,7 +389,7 @@ Note: *References to instance variables
 
 References allow template designers to generate dynamic content for web sites, while *directives* -- easy to use script elements that can be used to creatively manipulate the output of Java code -- permit web designers to truly take charge of the appearance and content of the web site.
 
-Directives always begin with a `#`.  Like references, the name of the directive may be bracketed by a `{` and a `}` symbol.  This is useful with directives that are immediately followed by text.  For example the following produces an error:
+Directives always begin with a `#`.  Like references, the name of the directive may be bracketed by a `{` and a `}` symbol.  This is useful with directives that are immediately followed by text.  For example the following will display `true enough#elseno way!`, which probably isn't the expected behavior.
 
     :::velocity
     #if($a==1)true enough#elseno way!#end

Modified: velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext?rev=1843797&r1=1843796&r2=1843797&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/vtl-reference.mdtext Sat Oct 13 22:31:47 2018
@@ -6,11 +6,23 @@ This guide is the reference for the Velo
 
 ## References
 
+In the following syntax references, *identifier* refers to:
+
+( **a..z**, **A..Z**, **_** ) [ ( **a..z**, **A..Z**, **0..9**, **_** ) , ( **a..z**, **A..Z**, **0..9**, **_** ), ... ]
+
+that is, a letter or an underscore followed by any number of letters, numbers and underscores.
+
+If the `parser.allows.dash.identifiers` configuration value is set to true, then the **-** dash is also allowed in identifiers (and must be surrounded by spaces to be interpreted as an arithmetic minus operator).
+
 ### Variables
 
 Notation:
 
-**$** [ **!** ][ **{** ][**a..z**, **A..Z** ][ **a..z**, **A..Z**, **0..9**, **_** ][ **}** ]
+**$** [ **!** ] [ **{** ] *identifier* [ [ **|** *alternate value* ] **}** ]
+
+Usage:
+
++ *alternate value*: alternate expression to use if the reference is null, empty, false or zero
 
 Examples:
 
@@ -18,6 +30,7 @@ Examples:
 + Silent Shorthand notation: `$!mudSlinger_9`
 + Formal notation: `${mudSlinger_9}`
 + Silent Formal notation: `$!{mudSlinger_9}`
++ Alternate value: `${mudSlinger_9|$otherWheels}`
 
 *Note that for backward compatibility reasons, it's possible to enable '**`-`**' as a valid character in variables identifiers, [see the parser configuration section](configuration.html#parser-configuration).*
 
@@ -25,24 +38,35 @@ Examples:
 
 Notation:
 
-**$** [ **{** ][ **a..z**, **A..Z** ][ **a..z**, **A..Z**, **0..9**, **_** ]* **.**[**a..z**, **A..Z** ][**a..z**, **A-Z**, **0..9**, **_** ]* [ **}** ]
+**$** [ **{** ] *identifier* **.** *identifier* [ [ **|** *alternate value* ] **}** ]
+
+Usage:
+
++ *alternate value*: alternate expression to use if the property is null, empty, false or zero
 
 Examples:
 
 + Regular Notation: `$customer.Address`
-<li>Formal Notation: `${purchase.Total}`
++ Formal Notation: `${purchase.Total}`
++ Alternate Value: `${person.name|'John Doe'}`
 
 ### Methods
 
 Notation:
 
-**$** [ **{** ][ **a..z**, **A..Z** ][ **a..z**, **A..Z**, **0..9**, **_** ]* **.**[ **a..z**, **A..Z** ][**a..z**, **A..Z**, **0..9**, **_** ]***(** [*optional parameter list...* ] **)** [** } **]
+**$** [ **{** ] *identifier* **.** *identifier* **(** [ *parameter list...* ] **)** [ [ **|** *alternate value* ] **}** ]
+
+Usage:
+
++ *alternate value*: alternate expression to use if the method returns null, empty, false or zero
++ *parameter list*: optional coma-separated list of expressions
 
 Examples:
 
 + Regular Notation: `$customer.getAddress()`
 + Formal Notation: `${purchase.getTotal()}`
 + Regular Notation with Parameter List: `$page.setTitle( "My Home Page" )`
++ Alternate value: `${page.getTitle()|'Blank Page'}`
 
 VTL Properties can be used as a shorthand notation for VTL Methods that take *get* and *set*. Either *$object.getMethod()* or *$object.setMethod()* can be abbreviated as *$object.Method*. It is generally preferable to use a Property when available. The main difference between Properties and Methods is that you can specify a parameter list to a Method.
 
@@ -54,12 +78,10 @@ Each method argument can be any valid VT
 
 Format:
 
-**#** [ **{** ] **set** [ **}** ] ** ( $**ref **=** [ **"**,
-    **'** ]arg[ **"**, **'** ] )
+**#** [ **{** ] **set** [ **}** ] **(** *$ref* **=** [ **"**, **'** ] *arg* [ **"**, **'** ] )
 
 Usage:
 
-
 + *$ref* - The LHS of the assignment must be a variable reference or a property reference.
 + *arg* - The RHS of the assignment, *arg* is parsed if enclosed in double quotes, and not parsed if enclosed in single quotes.  If the RHS evaluates to *null*, it is **not** assigned to the LHS.
 
@@ -86,7 +108,7 @@ The RHS can also be a simple arithmetic
 
 Format:
 
-**#** [ **{** ] **if** [ **}** ] **(** [condition] **)** [output] [**#** [ **{** ] **elseif** [ **}** ] **( **[condition] **)** [output] ]* [**#** [ **{** ] **else** [ **}** ]  [output] ] **#** [ **{** ] **end** [ **}** ]
+**#** [ **{** ] **if** [ **}** ] **(** *condition* **)** *output* [**#** [ **{** ] **elseif** [ **}** ] **(** *condition* **)** *output* ] [ **#** [ **{** ] **else** [ **}** ]  *output* ] **#** [ **{** ] **end** [ **}** ]
 
 Usage:
 
@@ -120,7 +142,7 @@ Boolean NOT | ! | not | `#if( !$foo )`
 
 Notes:
 
-1. The == operator can be used to compare numbers, strings, objects of the same class, or objects of different classes.  In the last case (when objects are of different classes), the toString() method is called on each object and the resulting Strings are compared.
+1. The == operator can be used to compare numbers, strings, objects of the same class, or objects of different classes.  In the last case (when objects are of different classes), if at least one the two objects cannot be converted to a number, the toString() method is called on each object and the resulting Strings are compared.
 2. You can also use brackets to delimit directives.  This is especially useful when text immediately follows an `#else` directive.
 
         :::velocity
@@ -130,7 +152,7 @@ Notes:
 
 Format:
 
-**#** [ **{** ] **foreach** [ **}** ] **(***$ref***in***arg***)***statement***#** [ **{** ] **end** [ **}** ]
+**#** [ **{** ] **foreach** [ **}** ] **(** *$ref* **in** *arg* **)** *statement* **#** [ **{** ] **end** [ **}** ]
 
 Usage:
 
@@ -163,7 +185,7 @@ Additionally, the maximum allowed number
 
 Format:
 
-**#** [ **{** ] **include** [ **}** ] **( **arg[ arg2  ... argn]** )**
+**#** [ **{** ] **include** [ **}** ] **(** *arg* [ *arg2*  ... *argn* ] **)**
 
 Usage:
 
@@ -178,7 +200,7 @@ Examples:
 
 Format:
 
-**#** [ **{** ] **parse** [ **}** ] **(** arg **)**</p>
+**#** [ **{** ] **parse** [ **}** ] **(** *arg* **)**</p>
 
 Usage:
 
@@ -215,7 +237,7 @@ This will break execution of the current
 
 Format:
 
-**#** [ **{** ] **evaluate** [ **}** ] **( **arg** )**
+**#** [ **{** ] **evaluate** [ **}** ] **(** *arg* **)**
 
 Usage:
 
@@ -230,7 +252,7 @@ Examples:
 
 Format:
 
-**#** [ **{** ] **define** [ **}** ] **( ***$ref*** )***statement***#** [ **{** ] **end** [ **}** ]
+**#** [ **{** ] **define** [ **}** ] **(* *$ref* **)** *statement* **#** [ **{** ] **end** [ **}** ]
 
 Usage:
 
@@ -245,14 +267,14 @@ Example:
 
 Format:
 
-**#** [ **{** ] **macro** [ **}** ] **(** vmname $arg1 [ = def1 ] [ $arg2 [ = def2 ] $arg3 [ = def3 ] ... $argn [ = defn ] ] **)** [ VM VTL code... ] **#** [ **{** ] **end** [ **}** ]
+**#** [ **{** ] **macro** [ **}** ] **(** *vmname* *$arg1* [ **=** *def1* ] [ *$arg2* [ **=** *def2* ] *$arg3* [ **=** def3 ] ... *$argn* [ **=** *defn* ] ] **)** [ *VTL code* ] **#** [ **{** ] **end** [ **}** ]
 
 Usage:
 
 + *vmname* - Name used to call the VM (*#vmname*)
 + *$arg1 $arg2 [ ... ]* - Arguments to the VM. There can be any number of arguments, but the number used at invocation must match the number specified in the definition, unless there is a default value provided for missing parameters.
 + *def1, def2, ...* - Optional default values provided for macro arguments. If a default value is provided for an argument, a default value must also be provided to all subsequent arguments.
-+ *[ VM VTL code... ]* - Any valid VTL code, anything you can put into a template, can be put into a VM.
++ *VTL code* - Any valid VTL code, anything you can put into a template, can be put into a VM.
 
 Once defined, the VM is used like any other VTL directive in a template.
 
@@ -285,7 +307,7 @@ Example:
 Example:
 
     :::velocity
-    #**
+    #*
       This is a multiline comment.
       This is the second line.
     *#