velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nbu...@apache.org
Subject svn commit: r753336 - in /velocity/engine/branches/2.0_Exp: src/changes/ xdocs/docs/ xdocs/docs/translations/
Date Fri, 13 Mar 2009 18:27:15 GMT
Author: nbubna
Date: Fri Mar 13 18:27:05 2009
New Revision: 753336

URL: http://svn.apache.org/viewvc?rev=753336&view=rev
Log:
VELOCITY-704 document changes (merge from trunk)

Modified:
    velocity/engine/branches/2.0_Exp/src/changes/changes.xml
    velocity/engine/branches/2.0_Exp/xdocs/docs/developer-guide.xml
    velocity/engine/branches/2.0_Exp/xdocs/docs/glossary.xml
    velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_es.xml
    velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fi.xml
    velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fr.xml
    velocity/engine/branches/2.0_Exp/xdocs/docs/user-guide.xml
    velocity/engine/branches/2.0_Exp/xdocs/docs/vtl-reference-guide.xml

Modified: velocity/engine/branches/2.0_Exp/src/changes/changes.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/changes/changes.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/changes/changes.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/changes/changes.xml Fri Mar 13 18:27:05 2009
@@ -26,7 +26,13 @@
 
   <body>
     <release version="2.0" date="In Subversion">
-      
+
+      <action type="add" dev="nbubna" issue="VELOCITY-704">
+    Remove features deprecated in 1.7 ($velocityCount, $velocityHasNext,
+    velocimacro.context.localscope, directive.evaluate.context.class and
+    all internal supporting code (ProxyVMContext, EvaluateContext, etc).
+      </action>
+
         <action type="add" dev="byron" issue="VELOCITY-697">
 	  Add ability to specify default values for macro parameters, e.g.;
 	  #macro(foo bar=1)
@@ -53,6 +59,52 @@
 
     <release version="1.7" date="In Subversion">
 
+      <action type="add" dev="nbubna" issue="VELOCITY-704">
+    Changed #stop to a directive implementation (get it out of the parser)
+    and allow it to accept a message as an argument to be written to the logs
+    for debugging purposes.
+      </action>
+
+      <action type="add" dev="nbubna" issue="VELOCITY-704">
+    Change the scoping behavior of Velocity, keeping it optional (everything global
+    scoped by default) but now providing an explicit namespace in content-containing
+    directives (like macros, #foreach, #parse, etc.) in which references that should
+    stay local may be kept.  This is accompanied by numerous related changes, including:
+    &lt;ul&gt;
+    &lt;li&gt;A Scope reference is now available within each content directive:
+        &lt;ul&gt;
+        &lt;li&gt;$template in Template.merge and #parse content&lt;li&gt;
+        &lt;li&gt;$macro in #macro&lt;/li&gt;
+        &lt;li&gt;$foreach in #foreach&lt;/li&gt;
+        &lt;li&gt;$evaluate in #evaluate or Velocity.evaluate(...) content&lt;/li&gt;
+        &lt;li&gt;$define in #define&lt;/li&gt;
+        &lt;li&gt;$&amp;lt;amacro&amp;gt; in #@&amp;lt;amacro&amp;gt;
+              (where &amp;lt;amacro&amp;gt; is the name of a macro being called with
a body)&lt;/li&gt;
+        &lt;/ul&gt;
+    &lt;/li&gt;
+    &lt;li&gt;Allowing the above to be suppressed by setting a velocity property
like:
+        &lt;br/&gt;&lt;code&gt;foreach.provide.scope.control = false&lt;/code&gt;&lt;/li&gt;
+    &lt;li&gt;When scopes of the same type are nested make the parent Scope available
+        through the child (e.g. $foreach.parent or $foreach.topmost).&lt;/li&gt;
+    &lt;li&gt;When a Scope reference overrides an existing reference that is not
a Scope,
+        make it available through the Scope (e.g. $foreach.replaced).&lt;/li&gt;
+    &lt;li&gt;Made #break work in any of the above scopes to exit the most immediate
one,
+        unless a different scope is provided as an argument
+        (e.g. #break($macro) or #break($foreach.topmost)).&lt;/li&gt;
+    &lt;li&gt;Deprecated $velocityCount;
+        please use $foreach.count or $foreach.index.&lt;/li&gt;
+    &lt;li&gt;Deprecated $velocityHasNext;
+        please use $foreach.hasNext, $foreach.first or $foreach.last&lt;/li&gt;
+    &lt;li&gt;Deprecated velocimacro.context.localscope setting;
+        please get/set local #macro references as members of the provided $macro
+        scope control instead. (e.g. #set( $macro.foo = 'bar' ) and $macro.foo ).&lt;/li&gt;
+    &lt;li&gt;Deprecated directive.evaluate.context.class setting;
+        please get/set local #evaluate references as members of the provided $evaluate
+        scope control instead. (e.g. #set( $evaluate.foo = 'bar' ) and $evaluate.foo ).&lt;/li&gt;
+    &lt;/ul&gt;
+    All of the deprecated features will be removed in Velocity 2.0.
+      </action>
+
       <action type="add" dev="nbubna" issue="VELOCITY-681">
     Calling #set on a macro argument (for which a #set-able reference
     was passed) will no longer propagate the new value to the original
@@ -70,7 +122,7 @@
       
       <action type="add" dev="byron"  issue="VELOCITY-673">
 	The non default VelocityEngine construtors now do not initialize the runtime
-	system so that properties may be set after constrution.  Also fixes an
+	system so that properties may be set after construction.  Also fixes an
 	Initialization race condition.
       </action>
 

Modified: velocity/engine/branches/2.0_Exp/xdocs/docs/developer-guide.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/xdocs/docs/developer-guide.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/xdocs/docs/developer-guide.xml (original)
+++ velocity/engine/branches/2.0_Exp/xdocs/docs/developer-guide.xml Fri Mar 13 18:27:05 2009
@@ -1610,36 +1610,36 @@
 </p>
 
 <p>
-<strong>#evaluate() Directive</strong>
+<strong>#define() Directive</strong>
 </p>
 
 <p>
-<code>directive.evaluate.context.class = org.apache.velocity.VelocityContext</code><br/>
-Used in the #evaluate() directive, defines the class that is used for the
-context local to the argument for #evaluate().
+<code>define.provide.scope.control = true</code><br/>
+Used to control the automatic provision of the $define scope control
+during #define() calls. The default is true.
+Set it to false if unused and you want a tiny performance boost.
 </p>
 
 <p>
-<strong>#foreach() Directive</strong>
+<strong>#evaluate() Directive</strong>
 </p>
 
 <p>
-<code>directive.foreach.counter.name = velocityCount</code><br/>
-Used in the #foreach() directive, defines the string to be used as the
-context key for the loop count. A template would access
-the loop count as $velocityCount.
+<code>evaluate.provide.scope.control = true</code><br/>
+Used to control the automatic provision of the $evaluate scope
+during #evaluate() or Velocity[Engine].evaluate(...) calls. The default
+is true.  Set it to false if unused and you want a tiny performance boost.
 </p>
 
 <p>
-<code>directive.foreach.iterator.name = velocityHasNext</code><br/>
-Used in the #foreach() directive, defines the string to be used as the
-context key for the "has next" value. A template would access
-this as $velocityHasNext.
+<strong>#foreach() Directive</strong>
 </p>
 
 <p>
-<code>directive.foreach.counter.initial.value = 1</code><br/>
-Default starting value for the loop counter reference in a #foreach() loop.
+<code>foreach.provide.scope.control = true</code><br/>
+Used to control the automatic provision of the $foreach scope
+during #foreach calls. The default is true.
+Set it to false if unused and you want a tiny performance boost.
 </p>
 
 <p>
@@ -1686,18 +1686,13 @@
 another template which itself may have a #parse() directive.  This value
 prevents runaway #parse() recursion.
 </p>
-
 <p>
-<strong>Math</strong>
+<code>template.provide.scope.control = true</code><br/>
+Used to control the automatic provision of the $template scope control
+during #parse calls (and template.merge(...) calls). The default is true.
+Set it to false if unused and you want a tiny performance boost.
 </p>
 
-<p>
-<code>resource.manager.logwhenfound = true</code><br/>
-Switch to control logging of 'found' messages from resource manager.
-When a resource is found for the first time, the resource name
-and classname of the loader that found it will be noted in the
-runtime log.
-</p>
 
 <p>
 <strong>Resource Management</strong>
@@ -1841,13 +1836,6 @@
 the override mechanism.
 </p>
 <p>
-<code>velocimacro.context.localscope = false</code><br/>
-Controls whether reference access (set/get) within a Velocimacro will change
-the context, or be of local scope in that
-Velocimacro.
-</p>
-
-<p>
 <code>velocimacro.library.autoreload = false</code><br/>
 Controls Velocimacro library autoloading.  When set to <code>true</code>
 the source Velocimacro library for an invoked Velocimacro will be checked
@@ -1874,6 +1862,19 @@
 The default reference name is "bodyContent" (e.g. $bodyContent).  This block
 macro feature was introduced in Velocity 1.7.
 </p>
+<p>
+<code>macro.provide.scope.control = true</code><br/>
+Used to control the automatic provision of the $macro scope control
+during #macro calls. The default is true.
+Set it to false if unused and you want a tiny performance boost.
+</p>
+<p>
+<code>&lt;somebodymacro&gt;.provide.scope.control = true</code><br/>
+Used to control the automatic provision of the $&lt;nameofthemacro&gt; scope control
+during a call to a macro with a body (e.g. #@foo #set($foo.a=$b) ... $foo.a #end).
+The default is true. Set it to false if you heavily use that body macro without
+using the scope control and you want a tiny performance boost.
+</p>
 
 <p>
 <strong>Strict Reference Setting</strong>

Modified: velocity/engine/branches/2.0_Exp/xdocs/docs/glossary.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/xdocs/docs/glossary.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/xdocs/docs/glossary.xml (original)
+++ velocity/engine/branches/2.0_Exp/xdocs/docs/glossary.xml Fri Mar 13 18:27:05 2009
@@ -39,12 +39,25 @@
     <code><a href="#macro">#macro</a></code> and ends with the 
     <code><a href="#end">#end</a></code> directive.</dd>
 
+    <dt><a name="break">#break</a></dt>
+    <dd>A <a href="#directive">directive</a> that stops the rendering
+    of the current (innermost) <a href="#contentdirective">content directive</a>
+    or a specified content directive if the <a href="#scopecontrol">scope control</a>
+    provided for that content directive is passed to #break as an argument:
+    (e.g. #break($foreach.parent)).</dd>
+
     <dt><a name="comment">Comment</a></dt>
     <dd>Allow descriptive text to be included in the template that will
     not be placed into the output of the template engine. Single line
     comments begin with <code>##</code>. Multi-line comments begin with
     <code>#*</code> and end with <code>*#</code></dd>
 
+    <dt><a name="contentdirective">Content Directive</a></dt>
+    <dd>A <a href="#directive">directive</a> that outputs content when
rendering
+    a <a href="#template">template</a>. The default ones automatically have
+    a <a href="#scopecontrol">scope control</a> made available in the
+    <a href="#context">during their rendering</a>.</dd>
+
     <dt><a name="context">Context</a></dt>
     <dd>A means to import Java objects into a <a href="#velocity">Velocity</a>
     <a href="#template">template</a>.</dd>
@@ -188,6 +201,14 @@
     <dt><a name="rhs">RHS</a></dt>
     <dd>Right Hand Side of an assignment</dd>
 
+    <dt><a name="scopecontrol">Scope Control</a></dt>
+    <dd>The <a href="#reference">reference</a> automatically provided
+    as a way of scoping/namespacing <a href="#reference">references</a>
+    (to avoid polluting the global <a href="#context">context</a>) within
+    the given content directive and also providing a "label" for
+    <a href="#break">#break</a> to use when breaking out of multiple
+    <a href="#contentdirective">content directives</a> at once.</dd>
+
     <dt><a name="set">#set</a></dt>
     <dd>The <a href="#directive">directive</a> that is used for setting
     the value of a reference.</dd>

Modified: velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_es.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_es.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_es.xml (original)
+++ velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_es.xml Fri Mar 13
18:27:05 2009
@@ -1249,32 +1249,11 @@
 <source><![CDATA[
 <table>
     #foreach( $cliente in $listaClientes )
-    <tr><td>$velocityCount</td><td>$cliente.Nombre</td></tr>
+    <tr><td>$foreach.count</td><td>$cliente.Nombre</td></tr>
 #end
 </table>
 ]]></source>
 
-<p>
-    El nombre por defecto para la referencia de la variable contador del
-    ciclo, que se especifica en el archivo
-    <code>velocity.properties</code>, es
-    $velocityCount. Por defecto el contador comienza en 1, pero esto se
-    puede hacer 0 o 1 en el archivo <code>velocity.properties</code>. A
-    continuación se muestra el fragmento de este archivo que corresponde
-    al contador de ciclo (en inglés, tal como aparece en el archivo
-    original):
-    </p>
-
-<source><![CDATA[
-# Default name of the loop counter
-# variable reference.
-directive.foreach.counter.nombre = velocityCount
-
-# Default starting value of the loop
-# counter variable reference.
-directive.foreach.counter.initial.value = 1
-]]></source>
-
  </section>
 
 <section name="Include" href="Include">
@@ -1658,15 +1637,6 @@
     </p>
 
     <p>
-    <code>velocimacro.context.localscope</code> -
-    Con valores posibles verdadero y falso (true y false), valor por
-    defecto falso. Cuando es verdadera cualquier modificación al
-    contexto por medio de un #set() dentro de un Velocimacro se
-    considera local a ese Velocimacro y no afecta permanentemente al
-    contexto.
-    </p>
-
-    <p>
     <code>velocimacro.library.autoreload</code> - Esta propiedad
     controla el cargado automático de la libreria de Velocimacros. El
     valor por defecto es <code>false</code>. Cuando es verdadero

Modified: velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fi.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fi.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fi.xml (original)
+++ velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fi.xml Fri Mar 13
18:27:05 2009
@@ -1269,28 +1269,11 @@
 <source><![CDATA[
 <table>
 #foreach( $asiakas in $asiakasLista )
-    <tr><td>$velocityCount</td><td>$asiakas.Nimi</td></tr>
+    <tr><td>$foreach.count</td><td>$asiakas.Nimi</td></tr>
 #end
 </table>
 ]]></source>
 
-    <p>
-    Silmukkalaskurin oletusnimi on $velocityCount ja se määritetään
-    velocity.properties tiedostossa. Oletuksena laskuri alkaa arvosta
-    1, mutta aloitusarvo voidaan määrittää olemaan joko 1 tai 0
-    <code>velocity.properties</code>
-    tiedostossa. <code>velocity.properties</code> tiedoston
-    silmukkalaskuriosio näyttää tältä:
-    </p>
-
-<source><![CDATA[
-# Silmukkalaskurin oletusnimi
-counter.name = velocityCount
-
-# Silmukkalaskurin aloitusarvo
-counter.initial.value = 1
-]]></source>
-
  </section>
 
 <section name="Include" href="Include">
@@ -1676,13 +1659,6 @@
     </p>
 
     <p>
-    <code>velocimacro.context.localscope</code> - Mahdolliset arvot
-    ovat true tai false, oletuksena false. Kun ominaisuuden arvoksi on
-    asetettu tosi, Velocimakroissa #set() ohjeella tehdyt muutokset
-    ovat 'paikallisia' eivätkä vaikuta pysyvästi muuttujien sisältöön.
-    </p>
-
-    <p>
     <code>velocimacro.library.autoreload</code> - Tämä ominaisuus
     ohjaa Velocimakrokirjaston automaattista uudelleenlatausta. Kun
     ominaisuus on asetettu arvoon <code>true</code> kutsutun

Modified: velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fr.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fr.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fr.xml (original)
+++ velocity/engine/branches/2.0_Exp/xdocs/docs/translations/user-guide_fr.xml Fri Mar 13
18:27:05 2009
@@ -901,7 +901,7 @@
   <source><![CDATA[
 <table>
 #foreach( $customer in $customerList )
-    <tr><td>$velocityCount</td><td>$customer.Name</td></tr>
+    <tr><td>$foreach.count</td><td>$customer.Name</td></tr>
 #end
 </table>
 ]]></source>
@@ -911,24 +911,6 @@
   $customer.Name #if( $velocityHasNext ),#end
 #end   
 ]]></source>
-  <p>
-    Le nom de la référence du compteur de bouche est spécifié dans le fichier
-    <code>velocity.properties</code>, sa valeur par défaut est <em>$velocityCount</em>.
De même pour le nom de  la
-    référence indiquant si l'on est sur la dernière itération, dont la valeur
par défaut est <em>$velocityHasNext</em>.
-    Par défaut le compteur démarre à 1, mais ceci aussi peut être paramétré
(à 0 ou 1)
-    dans le fichier <code>velocity.properties</code>. Voici à quoi ressemble
la section Propriétés du compteur de boucle
-    dans le fichier <code>velocity.properties</code>:
-  </p>
-  <source><![CDATA[
-# Default name of the loop counter
-# variable reference.
-directive.foreach.counter.name = velocityCount
-directive.foreach.iterator.name = velocityHasNext 
-
-# Default starting value of the loop
-# counter variable reference.
-directive.foreach.counter.initial.value = 1
-]]></source>
 <p>Il est possible de définir le maximum autorisé du nombre de fois qu'une boucle
peut être exécutée. Par défaut il
 n'y a pas de maximum (c'est indiqué par la valeur 0 ou moins), mais on peut le fixer à
un nombre arbitraire dans le
 fichier <code>velocity.properties</code>. Cela peut être utile comme garde-fou.</p>
@@ -941,7 +923,7 @@
 <source><![CDATA[
 ## list first 5 customers only
 #foreach( $customer in $customerList )
-  #if( $velocityCount > 5 )
+  #if( $foreach.count > 5 )
     #break
   #end
   $customer.Name
@@ -1226,11 +1208,6 @@
     par la première VM quand celle-ci est appelée elle-même dans le gabarit. Aucun
autre gabarit n'est affecté.
   </p>
   <p>
-    <code>velocimacro.context.localscope</code> - Cette propriété peut
valoir true ou false, la valeur par défaut est
-    false. Quand elle vaut true, toute modification du contexte via #set() à l'intérieur
d'une Velocimacro est considérée
-    'locale' à cette Velocimacro et n'affectera pas le contexte de façon permanente.
-  </p>
-  <p>
     <code>velocimacro.library.autoreload</code> - Cette propriété contrôle
le chargement automatique de la bibliothèque
     de Velocimacro. La valeur par défaut est <code>false</code>. Quand elle
est positionnée à <code>true</code>
     la bibliothèque source appelée pour une Velocimacro sera vérifiée pour voir
si elle a changé et sera rechargée

Modified: velocity/engine/branches/2.0_Exp/xdocs/docs/user-guide.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/xdocs/docs/user-guide.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/xdocs/docs/user-guide.xml (original)
+++ velocity/engine/branches/2.0_Exp/xdocs/docs/user-guide.xml Fri Mar 13 18:27:05 2009
@@ -67,6 +67,7 @@
         <li><a href="#Loops">Foreach Loops</a></li>
         <li><a href="#Include">Include</a></li>
         <li><a href="#Parse">Parse</a></li>
+        <li><a href="#Break">Break</a></li>
         <li><a href="#Stop">Stop</a></li>
         <li><a href="#Evaluate">Evaluate</a></li>
         <li><a href="#Define">Define</a></li>
@@ -1376,7 +1377,7 @@
 <source><![CDATA[
 <table>
 #foreach( $customer in $customerList )
-    <tr><td>$velocityCount</td><td>$customer.Name</td></tr>
+    <tr><td>$foreach.count</td><td>$customer.Name</td></tr>
 #end
 </table>
 ]]></source>
@@ -1388,32 +1389,19 @@
 
 <source><![CDATA[
 #foreach( $customer in $customerList )
-    $customer.Name#if( $velocityHasNext ),#end
+    $customer.Name#if( $foreach.hasNext ),#end
 #end
 ]]></source>
 
     <p>
-    The default name for the "has next" variable reference, which is
-    specified in the velocity.properties file, is $velocityHasNext. 
-    The default name for the loop counter variable reference, which is
-    specified in the velocity.properties file, is $velocityCount. By
-    default the counter starts at 1, but this can be set to either 0 or
-    1 in the <code>velocity.properties</code> file. Here's what the loop
-    counter properties section of the <code>velocity.properties</code>
-    file appears:
+    If you want a zero-based index of the #foreach loop, you can just
+    use $foreach.index instead of $foreach.count.  Likewise, $foreach.first
+    and $foreach.last are provided to compliment $foreach.hasNext.
+    If you want to access these properties for an outer #foreach loop, you
+    can reference them directly through the $foreach.parent or $foreach.topmost
+    properties (e.g. $foreach.parent.index or $foreach.topmost.hasNext).
     </p>
 
-<source><![CDATA[
-# Default name of the loop counter
-# variable reference.
-directive.foreach.counter.name = velocityCount
-directive.foreach.iterator.name = velocityHasNext
-
-# Default starting value of the loop
-# counter variable reference.
-directive.foreach.counter.initial.value = 1
-]]></source>
-
     <p>
     It's possible to set a maximum allowed number of times that a loop
     may be executed. By default there is no max (indicated by a value of 0
@@ -1434,7 +1422,7 @@
 <source><![CDATA[
 ## list first 5 customers only
 #foreach( $customer in $customerList )
-    #if( $velocityCount > 5 )
+    #if( $foreach.count > 5 )
         #break
     #end
     $customer.Name
@@ -1545,6 +1533,28 @@
 
  </section>
 
+<section name="Break" href="break">
+
+    <p>
+    The <em>#break</em> directive stops any further rendering of the current
+    execution scope.  An "execution scope" is essentially any directive with
+    content (i.e. #foreach, #parse, #evaluate, #define, #macro, or #@somebodymacro)
+    or any "root" scope (i.e. template.merge(...), Velocity.evaluate(...) or
+    velocityEngine.evaluate(...)). Unlike #stop, #break will only stop the
+    innermost, immediate scope, not all of them.
+    </p>
+
+    <p>If you wish to break out of a specific execution scope that is not
+    necessarily the most immediate one, then you can pass the scope control
+    reference (i.e. $foreach, $template, $evaluate, $define, $macro, or
+    $somebodymacro) as an argument to #break. (e.g. #break($macro)). This
+    will stop rendering of all scopes up to the specified one.  When within
+    nested scopes of the same type, remember that you can always access the
+    parent(s) via $&lt;scope&gt;.parent or $&lt;scope&gt;.topmost and pass
those
+    to #break instead (e.g. #break($foreach.parent) or #break($macro.topmost)).
+    </p>
+
+</section>
 
 <section name="Stop" href="stop">
 
@@ -1554,7 +1564,9 @@
     another template accessed through #parse or located in a velocity macro.
     The resulting merged output will contain all the content up to the point
     the #stop directive was encountered.  This is handy as an early exit from
-    a template.
+    a template. For debugging purposes, you may provide a message argument
+    (e.g. #stop('$foo was not in context') ) that will be written to the logs
+    (DEBUG level, of course) upon completion of the stop command.
     </p>
 
  </section>
@@ -1879,14 +1891,6 @@
     </p>
 
     <p>
-    <code>velocimacro.context.localscope</code> - This property has the
-    possible values true or false, and the default is false.  When true,
-    any modifications to the context via #set() within a Velocimacro
-    are considered 'local' to the Velocimacro, and will not
-    permanently affect the context.
-    </p>
-
-    <p>
     <code>velocimacro.library.autoreload</code> - This property
      controls Velocimacro library autoloading. The default value
     is <code>false</code>.  When set to <code>true</code>

Modified: velocity/engine/branches/2.0_Exp/xdocs/docs/vtl-reference-guide.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/xdocs/docs/vtl-reference-guide.xml?rev=753336&r1=753335&r2=753336&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/xdocs/docs/vtl-reference-guide.xml (original)
+++ velocity/engine/branches/2.0_Exp/xdocs/docs/vtl-reference-guide.xml Fri Mar 13 18:27:05
2009
@@ -335,31 +335,12 @@
 <source><![CDATA[
 <table>
 #foreach( $customer in $customerList )
-    <tr><td>$velocityCount</td><td>$customer.Name</td></tr>
+    <tr><td>$foreach.count</td><td>$customer.Name</td></tr>
 #end
 </table>
 ]]></source>
 
     <p>
-    The default name for the loop counter variable reference, which is
-    specified in the velocity.properties file, is $velocityCount. By
-    default the counter starts at 1, but this can be set to either 0 or
-    1 in the <code>velocity.properties</code> file. Here's what the loop
-    counter properties section of the <code>velocity.properties</code>
-    file appears:
-    </p>
-
-<source><![CDATA[
-# Default name of the loop counter
-# variable reference.
-directive.foreach.counter.name = velocityCount
-
-# Default starting value of the loop
-# counter variable reference.
-directive.foreach.counter.initial.value = 1
-]]></source>
-
-    <p>
     Additionally, the maximum allowed number of loop iterations can be
     controlled engine-wide (an ability introduced in Velocity 1.5).
     By default, there is no limit:
@@ -443,6 +424,27 @@
     </p>
   </subsection>
 
+  <subsection name="#break - Stops the current directive" href="break-Stopsthecurrentdirective">
+    <p>
+    Format:
+    </p>
+
+    <p>
+    <strong>#</strong> [ <strong>{</strong> ] <strong>break</strong>
[ <strong>}</strong> ]
+    </p>
+
+    <p>
+    Usage:
+    </p>
+
+    <p>
+    This will break execution of the current content directive. This is good for
+    exiting a #foreach loop early, but also works in other scopes. You can even
+    pass the scope control reference for a specific outer scope to break execution
+    of all scopes outward to the specified one.
+    </p>
+  </subsection>
+
   <subsection name="#evaluate - Dynamically evaluates a string or reference" href="evaluate">
     <p>
     Format:



Mime
View raw message