engine/2.1/vtl-reference.html - velocity-site - Git at Google

 <!DOCTYPE html>
 <!--
     Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
     regarding copyright ownership.  The ASF licenses this file
     to you under the Apache License, Version 2.0 (the
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
     specific language governing permissions and limitations
     under the License.
   -->
 <html lang="en">
   <head>
     <title>Apache Velocity Engine VTL Reference</title>

     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
     <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />

     <link rel="stylesheet" type="text/css" href="/css/site.css">


   </head>

   <body>
     <div id="page">
       <div id="header">

         <div id="logo2"><img src="/engine/devel/images/velocity-logo.png"/></div>

         <a href="/">
 <svg height="60" width="50%" viewBox="20 20 800 110" preserveAspectRatio="xMinYMin">
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1395.619" x2="-4570.1162" y1="697.55487" x1="-5167.0962" gradientUnits="userSpaceOnUse" id="SVGID_1_">
     <stop id="stop3521" style="stop-color:#F69923" offset="0" />
     <stop id="stop3523" style="stop-color:#F79A23" offset="0.3123" />
     <stop id="stop3525" style="stop-color:#E97826" offset="0.8383" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="620.50482" x2="-5326.209" y1="620.50482" x1="-9585.3418" gradientUnits="userSpaceOnUse" id="SVGID_2_">
     <stop id="stop3546" style="stop-color:#9E2064" offset="0.3233" />
     <stop id="stop3548" style="stop-color:#C92037" offset="0.6302" />
     <stop id="stop3550" style="stop-color:#CD2335" offset="0.7514" />
     <stop id="stop3552" style="stop-color:#E97826" offset="1" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1047.6898" x2="-6533.1782" y1="1047.6898" x1="-9071.207" gradientUnits="userSpaceOnUse" id="SVGID_3_">
     <stop id="stop3557" style="stop-color:#282662" offset="0" />
     <stop id="stop3559" style="stop-color:#662E8D" offset="9.548390e-02" />
     <stop id="stop3561" style="stop-color:#9F2064" 1  offset="0.7882" />
     <stop id="stop3563" style="stop-color:#CD2032" offset="0.9487" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="580.81702" x2="-5086.9941" y1="580.81702" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_4_">
     <stop id="stop3568" style="stop-color:#9E2064" offset="0.3233" />
     <stop id="stop3570" style="stop-color:#C92037" offset="0.6302" />
     <stop id="stop3572" style="stop-color:#CD2335" offset="0.7514" />
     <stop id="stop3574" style="stop-color:#E97826" offset="1" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="638.4408" x2="-6797.2012" y1="638.4408" x1="-9035.5029" gradientUnits="userSpaceOnUse" id="SVGID_5_">
     <stop id="stop3579" style="stop-color:#282662" offset="0" />
     <stop id="stop3581" style="stop-color:#662E8D" offset="9.548390e-02" />
     <stop id="stop3583" style="stop-color:#9F2064" offset="0.7882" />
     <stop id="stop3585" style="stop-color:#CD2032" offset="0.9487" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1021.6218" x2="-5086.9941" y1="1021.6218" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_6_">
     <stop id="stop3590" style="stop-color:#9E2064" offset="0.3233" />
     <stop id="stop3592" style="stop-color:#C92037" offset="0.6302" />
     <stop id="stop3594" style="stop-color:#CD2335" offset="0.7514" />
     <stop id="stop3596" style="stop-color:#E97826" offset="1" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="999.73297" x2="-5351.2017" y1="999.73297" x1="-9610.334" gradientUnits="userSpaceOnUse" id="SVGID_7_">
     <stop id="stop3601" style="stop-color:#9E2064" offset="0.3233" />
     <stop id="stop3603" style="stop-color:#C92037" offset="0.6302" />
     <stop id="stop3605" style="stop-color:#CD2335" offset="0.7514" />
     <stop id="stop3607" style="stop-color:#E97826" offset="1" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1152.7261" x2="-5086.9941" y1="1152.7261" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_8_">
     <stop id="stop3616" style="stop-color:#9E2064" offset="0.3233" />
     <stop id="stop3618" style="stop-color:#C92037" offset="0.6302" />
     <stop id="stop3620" style="stop-color:#CD2335" offset="0.7514" />
     <stop id="stop3622" style="stop-color:#E97826" offset="1" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1137.7247" x2="-5086.9941" y1="1137.7247" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_9_">
     <stop id="stop3631" style="stop-color:#9E2064" offset="0.3233" />
     <stop id="stop3633" style="stop-color:#C92037" offset="0.6302" />
     <stop id="stop3635" style="stop-color:#CD2335" offset="0.7514" />
     <stop id="stop3637" style="stop-color:#E97826" offset="1" />
   </linearGradient>
   <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1134.7161" x2="-6011.9995" y1="1134.7161" x1="-6953.4072" gradientUnits="userSpaceOnUse" id="SVGID_10_">
     <stop id="stop3646" style="stop-color:#9E2064" offset="0.3233" />
     <stop id="stop3648" style="stop-color:#C92037" offset="0.6302" />
     <stop id="stop3650" style="stop-color:#CD2335" offset="0.7514" />
     <stop id="stop3652" style="stop-color:#E97826" offset="1" />
   </linearGradient>
   <g transform="translate(275,-230)" id="g3735">
     <path d="m 95.030525,353.34688 c -5.868388,1.89866 -18.455097,2.86966 -35.232972,2.68962 l -7.844759,-17.69411 c 11.922072,0.96277 23.155947,1.27149 33.446456,0.7785 0.806681,-0.0278 1.205437,-0.0597 1.205437,-0.0597 -0.39975,0.0215 -0.805689,0.0382 -1.205437,0.0597 -3.380984,0.11837 -13.97859,0.22097 -32.909158,-1.88263 6.824373,-6.72909 18.288583,-16.31958 28.008861,-23.85834 18.433387,9.69185 21.017957,20.51606 21.017957,20.51606 0,0 5.61321,15.54576 -6.486385,19.4509 z" id="path3527" style="fill:url(#SVGID_1_)" />
     <path d="m 3.8322454,303.07135 c 0.059217,-0.0415 0.1120778,-0.0878 0.1712971,-0.12929 l -1.0221478,0.89604 c -0.088131,0.0386 -0.1658908,0.0658 -0.2478563,0.10915 0.3676459,-0.29732 0.7362578,-0.58424 1.098707,-0.8759 z" id="path3529" style="fill:none" />
     <path d="m -27.876072,290.63399 c -0.650899,0.45658 -1.281214,0.94828 -1.904317,1.45519 0.623103,-0.50691 1.259608,-0.99386 1.904317,-1.45519 z" id="path3531" style="fill:none" />
     <path d="m -128.18492,294.56272 c 0.27819,0.088 0.55639,0.17608 0.82938,0.26978 5.73136,1.8314 11.32321,3.58465 16.79937,5.26839 6.14427,1.88764 12.119072,3.68379 17.941982,5.39228 6.136306,1.80423 12.096924,3.5122 17.888098,5.1287 6.074555,1.69886 11.961044,3.29193 17.65531,4.79537 4.634037,1.22062 9.141965,2.38304 13.528979,3.48159 1.458542,0.36649 2.910894,0.72823 4.350865,1.08046 2.85092,0.70149 5.659501,1.38013 8.402938,2.03773 2.537553,0.60576 5.026574,1.18393 7.479394,1.74394 0.816212,0.19205 1.625242,0.36892 2.435266,0.55621 0.129295,0.0317 0.263817,0.0577 0.393113,0.0893 l -0.868431,0.76291 0.823816,1.77257 c -0.199639,-0.047 -0.398312,-0.0837 -0.603148,-0.12504 -3.709945,-0.80082 -7.434286,-1.63202 -11.17299,-2.49357 -2.160061,-0.49944 -4.326285,-1.00361 -6.493528,-1.51823 -6.008289,-1.42577 -12.02773,-2.90842 -18.046963,-4.44886 -6.083384,-1.55106 -12.155172,-3.16085 -18.201961,-4.8094 -5.94027,-1.61506 -11.850346,-3.27456 -17.722022,-4.95287 -5.860317,-1.67925 -11.671838,-3.38866 -17.421218,-5.10831 -6.00377,-1.79907 -11.9226,-3.61019 -17.74509,-5.43429 -1.31344,-0.40964 -2.62686,-0.81925 -3.9351,-1.23456 -4.69313,-1.47853 -9.30551,-2.95301 -13.84851,-4.42253 l -1.30665,-2.80027 0.97437,-0.85544 c 0.1365,0.0469 0.27298,0.0937 0.4033,0.1358 5.95137,1.97137 11.76945,3.86936 17.45943,5.68831 z" id="path3533" style="fill:none" />
     <path d="m -30.254972,292.46861 0,0 c 0.0052,-0.006 0.01127,-0.001 0.01647,-0.007 0,0 -0.0052,0.006 -0.01647,0.007 z" id="path3535" style="fill:none" />
     <path d="m -44.667842,285.26517 c -0.973928,0.73986 -1.967656,1.51281 -2.988395,2.30367 -0.0052,0.006 -0.01647,0.007 -0.02166,0.0123 0.500572,-0.40778 0.995948,-0.80989 1.498505,-1.19683 0.50256,-0.38694 1.00094,-0.75776 1.511673,-1.1191 z" id="path3537" style="fill:#be202e" />
     <path d="m -44.667842,285.26517 c -0.973928,0.73986 -1.967656,1.51281 -2.988395,2.30367 -0.0052,0.006 -0.01647,0.007 -0.02166,0.0123 0.500572,-0.40778 0.995948,-0.80989 1.498505,-1.19683 0.50256,-0.38694 1.00094,-0.75776 1.511673,-1.1191 z" id="path3539" style="opacity:0.35;fill:#be202e" />
     <path d="m -30.2218,292.45544 c 0,0 -0.0052,0.006 -0.01127,10e-4 -0.0052,0.006 -0.01127,9.9e-4 -0.01647,0.007 0.153662,-0.13318 0.314646,-0.25108 0.463195,-0.37852 0.628302,-0.51257 1.264807,-0.99953 1.904289,-1.45521 -0.763241,0.60216 -1.549259,1.20616 -2.339509,1.82623 l 0,0 0,0 z" id="path3541" style="fill:#be202e" />
     <path d="m -30.2218,292.45544 c 0,0 -0.0052,0.006 -0.01127,10e-4 -0.0052,0.006 -0.01127,9.9e-4 -0.01647,0.007 0.153662,-0.13318 0.314646,-0.25108 0.463195,-0.37852 0.628302,-0.51257 1.264807,-0.99953 1.904289,-1.45521 -0.763241,0.60216 -1.549259,1.20616 -2.339509,1.82623 l 0,0 0,0 z" id="path3543" style="opacity:0.35;fill:#be202e" />
     <path d="m -3.0502818,330.5069 c 6.1572269,1.1827 12.247534,2.26571 18.2471238,3.24041 6.227231,1.01426 12.356561,1.90504 18.357978,2.65895 0.348762,0.0456 0.708911,0.0903 1.063863,0.1407 5.913525,0.73472 11.699134,1.33257 17.339307,1.78976 l 7.844762,17.69411 c -1.160612,-0.0121 -2.333632,-0.0338 -3.529455,-0.0536 -4.497401,-0.0917 -9.271992,-0.26093 -14.266831,-0.51239 -5.629411,-0.28469 -11.556567,-0.6821 -17.699796,-1.1778 -5.67533,-0.46487 -11.549098,-1.02415 -17.5529729,-1.68334 -5.1106845,-0.5626 -10.3308648,-1.18997 -15.622198,-1.90096 -0.197654,-0.0262 -0.3953057,-0.0524 -0.5929873,-0.0786 L -20.52484,326.94198 c 5.866009,1.25856 11.69707,2.45163 17.4745582,3.56492 z" id="path3554" style="fill:url(#SVGID_2_)" />
     <path d="m -148.64432,287.87492 c -4.62455,-1.5418 -9.31626,-3.12551 -14.09367,-4.76537 -0.0714,-0.0258 -0.13651,-0.0469 -0.20787,-0.0727 -0.67629,-0.2295 -1.34737,-0.46467 -2.02369,-0.69419 -3.21697,-1.10818 -6.09263,-2.12815 -12.63913,-4.44059 1.0996,-3.6285 -0.41103,-8.38228 -2.49019,-13.37944 3.85283,3.31605 6.24773,7.77315 6.52364,12.94094 11.22895,-13.43253 25.02773,-21.83891 40.65304,-19.66506 1.39603,0.1929 2.79384,0.46445 4.21819,0.83367 -6.03156,-0.16844 -10.5525,1.89547 -15.78323,8.30262 -0.0165,0.007 -0.0384,0.0188 -0.0549,0.0255 0.0165,-0.007 0.0384,-0.0188 0.0549,-0.0255 12.65883,-5.62036 21.02643,-6.89439 31.69203,-5.50534 2.52825,0.32813 5.18536,0.80351 8.06151,1.40845 -16.05366,1.09099 -26.93227,8.28126 -33.83488,19.35554 l -7.46769,6.54422 c -0.87076,-0.28223 -1.73631,-0.57012 -2.60806,-0.86277 z" id="path3565" style="fill:url(#SVGID_3_)" />
     <path d="m -127.92557,298.05617 c 5.82769,1.81842 11.74652,3.62955 17.74512,5.43431 5.74415,1.7253 11.554681,3.42428 17.421188,5.10828 5.866507,1.68401 11.775562,3.33306 17.722022,4.95287 6.046789,1.64856 12.123776,3.25267 18.201961,4.8094 6.013043,1.53569 12.038702,3.02311 18.046963,4.44886 2.167243,0.51462 4.333467,1.0188 6.493528,1.51824 3.738705,0.86155 7.463045,1.69274 11.172991,2.49357 0.199636,0.047 0.398312,0.0837 0.603147,0.12503 l 11.0633797,23.68219 c -0.3953333,-0.0524 -0.7854697,-0.11047 -1.1807777,-0.16285 -5.606921,-0.76978 -11.295338,-1.6118 -17.027898,-2.55534 -5.790549,-0.94943 -11.619023,-1.99561 -17.461681,-3.12996 -4.930086,-0.95526 -9.854792,-1.97402 -14.768868,-3.06189 -0.99728,-0.22482 -1.97698,-0.44581 -2.962873,-0.67154 -6.150175,-1.40914 -11.974938,-2.89686 -17.487932,-4.42532 -6.244233,-1.73255 -12.086525,-3.52355 -17.517683,-5.33696 -3.574927,-1.18983 -6.978977,-2.39336 -10.215327,-3.58405 -2.73994,-1.04133 -5.46008,-2.11577 -8.13662,-3.21469 -6.31977,-2.58273 -12.45563,-5.34303 -18.38577,-8.29314 l -11.10848,-23.79411 c 4.54303,1.46954 9.15538,2.94401 13.84853,4.42255 1.30203,0.41054 2.62167,0.82493 3.93508,1.23455 z" id="path3576" style="fill:url(#SVGID_4_)" />
     <path d="m -135.39748,315.78421 c -7.2115,-3.62494 -14.10198,-7.55402 -20.5914,-11.85137 -0.2272,-0.15514 -0.45863,-0.29422 -0.68582,-0.44936 2.3312,6.55285 0.24599,17.70369 0.21823,17.65338 -3.57467,-11.87432 -8.27251,-22.40852 -15.98628,-29.36565 -3.27442,2.37386 -5.94744,7.01608 -8.28358,12.96033 -0.41103,-8.38228 1.53485,-12.94527 2.45003,-14.5997 -4.28418,4.11989 -11.70198,6.14259 -19.64656,7.81875 9.09151,-4.3892 15.21177,-8.8767 17.7976,-13.46995 -24.55723,-8.42409 -51.09999,-18.3439 -78.93127,-29.25317 2.33282,-1.41596 4.74343,-1.47765 7.19121,-0.67033 5.0236,1.99314 38.05928,14.98608 83.16344,30.23283 1.28124,0.43321 2.57389,0.86552 3.8727,1.30257 0.36193,0.12335 0.72908,0.24106 1.08481,0.35966 4.73826,1.59047 9.59244,3.19267 14.55737,4.81229 1.13136,0.36642 2.26272,0.73284 3.40026,1.10401 0.0237,0.009 0.0476,0.0172 0.0652,0.021 l 11.11272,23.77804 c -0.25321,-0.12682 -0.52301,-0.24705 -0.7886,-0.38338 z" id="path3587" style="fill:url(#SVGID_5_)" />
     <path d="m -20.879529,324.31241 c -0.803833,-0.18253 -1.613855,-0.36983 -2.435266,-0.5562 -2.447621,-0.56569 -4.936644,-1.14385 -7.479421,-1.74397 -2.748608,-0.6519 -5.5458,-1.33146 -8.402911,-2.03771 -1.439971,-0.35222 -2.880933,-0.71488 -4.350864,-1.08045 -4.387015,-1.09855 -8.894942,-2.26097 -13.528979,-3.48159 -5.694267,-1.50344 -11.580756,-3.09652 -17.65531,-4.79538 -5.791175,-1.61649 -11.75182,-3.32448 -17.888098,-5.1287 -5.82291,-1.70849 -11.803902,-3.50939 -17.941982,-5.39227 -5.47616,-1.68374 -11.06801,-3.43699 -16.79937,-5.26839 -0.27821,-0.088 -0.55639,-0.17608 -0.82938,-0.26978 -5.68998,-1.81895 -11.50806,-3.71694 -17.44804,-5.68923 -0.13651,-0.0469 -0.27299,-0.0937 -0.40331,-0.1358 l 7.4677,-6.54423 c -0.099,0.16552 -0.21555,0.32718 -0.31452,0.4927 9.07173,-7.71799 26.60886,-13.7657 42.082402,-14.50031 7.130974,-0.33982 14.689435,0.18964 22.840099,1.56994 6.067741,1.02703 12.461933,2.52695 19.257152,4.49905 5.938834,1.72022 12.180797,3.78914 18.773426,6.22395 -2.953943,1.10323 -5.869407,2.7287 -8.744022,4.78162 -0.499373,0.3604 -1.009112,0.73216 -1.511672,1.1191 -0.502585,0.38691 -1.004151,0.78427 -1.498505,1.19683 l 0,0 0,0 c 0.0052,-0.006 0.01647,-0.007 0.02166,-0.0123 10.741665,-5.44059 21.911677,-5.49972 33.275347,-3.05294 -3.512293,0.90633 -8.725108,2.75774 -13.490013,6.1124 -0.650869,0.45659 -1.281184,0.9483 -1.904287,1.4552 -0.160021,0.1283 -0.314677,0.25106 -0.463195,0.37852 l 0,0 0,0 c 0.0052,-0.006 0.01127,-9.9e-4 0.01647,-0.007 0,0 0.0052,-0.006 0.01127,-9.9e-4 l 0,0 c 3.833524,-1.80927 7.415482,-3.06785 10.971709,-3.81484 0.75953,-0.16062 1.521076,-0.30038 2.285595,-0.40887 1.160272,-0.17169 2.320337,-0.28559 3.490588,-0.35301 0.747698,-0.0441 1.497407,-0.0674 2.255322,-0.065 1.7736055,-1.9e-4 3.5809872,0.11249 5.4459147,0.34666 0.5691898,0.07 1.1394009,0.1504 1.7219926,0.24033 0.8080111,0.16642 1.5932437,0.33468 2.3670894,0.50385 3.4947139,0.7708 6.5151055,1.56378 9.1028098,2.33365 1.2938545,0.38493 2.4717831,0.75813 3.5461715,1.12911 0.427069,0.1444 0.842778,0.28973 1.24088,0.4312 1.189109,0.43009 2.22612,0.83033 3.11722,1.20547 1.333581,0.56035 2.345383,1.05716 3.054216,1.4469 l 0,0 0,0 c -0.484902,0.0914 -1.006187,0.22239 -1.55767,0.39787 -3.810562,1.20862 -9.0630554,4.26613 -12.8155016,7.10372 l 6.8589836,-6.00695 -6.8589836,6.00695 c -0.059219,0.0415 -0.1120802,0.0878 -0.1712972,0.1293 -0.3686395,0.2869 -0.73626,0.58424 -1.1100962,0.87681 0.088156,-0.0386 0.1659184,-0.0658 0.2478563,-0.10915 l -23.4688293,20.55321 c -0.123105,-0.0269 -0.246211,-0.0538 -0.380705,-0.0798 z" id="path3598" style="fill:url(#SVGID_6_)" />
     <path d="m 52.489098,337.22784 c -5.221409,-0.58001 -11.072737,-1.32494 -17.582802,-2.29555 -0.337345,-0.0465 -0.687098,-0.10255 -1.030661,-0.15384 -5.631475,-0.8466 -11.74798,-1.84346 -18.359704,-3.03705 -5.7115598,-1.02402 -11.780866,-2.1875 -18.2388704,-3.51423 -5.6261705,-1.15166 -11.5511356,-2.4265 -17.7644676,-3.83584 L 2.9813947,303.8381 c 9.3594193,-4.04821 15.0606363,-4.69376 22.0219053,-4.22681 1.892116,0.15844 3.845172,0.35401 5.836389,0.58854 6.095793,0.72012 12.552647,1.79478 18.766426,3.08853 5.997499,1.25326 11.744739,2.71043 16.714058,4.25614 3.159483,0.98674 6.000949,2.00943 8.377522,3.03258 2.095388,0.90383 4.020884,1.83177 5.804442,2.7763 -9.724453,7.55488 -21.194854,17.14061 -28.013039,23.87446 z" id="path3609" style="fill:url(#SVGID_7_)" />
     <path d="m -46.179514,286.38427 c -0.502558,0.38693 -1.004124,0.78429 -1.498506,1.19682 l 0,0 c 0.494382,-0.41253 0.995948,-0.80989 1.498506,-1.19682 z" id="path3611" style="fill:#be202e" />
     <path d="m -46.179514,286.38427 c -0.502558,0.38693 -1.004124,0.78429 -1.498506,1.19682 l 0,0 c 0.494382,-0.41253 0.995948,-0.80989 1.498506,-1.19682 z" id="path3613" style="opacity:0.35;fill:#be202e" />
     <path d="m -46.179514,286.38427 c -0.502558,0.38693 -1.004124,0.78429 -1.498506,1.19682 l 0,0 c 0.494382,-0.41253 0.995948,-0.80989 1.498506,-1.19682 z" id="path3624" style="fill:url(#SVGID_8_)" />
     <path d="m -30.254972,292.46861 c 0.153663,-0.13318 0.314647,-0.25107 0.463193,-0.37852 -0.148463,0.12751 -0.303257,0.25016 -0.463193,0.37852 l 0,0 z" id="path3626" style="fill:#be202e" />
     <path d="m -30.254972,292.46861 c 0.153663,-0.13318 0.314647,-0.25107 0.463193,-0.37852 -0.148463,0.12751 -0.303257,0.25016 -0.463193,0.37852 l 0,0 z" id="path3628" style="opacity:0.35;fill:#be202e" />
     <path d="m -30.254972,292.46861 c 0.153663,-0.13318 0.314647,-0.25107 0.463193,-0.37852 -0.148463,0.12751 -0.303257,0.25016 -0.463193,0.37852 l 0,0 z" id="path3639" style="fill:url(#SVGID_9_)" />
     <path d="m -30.233189,292.45636 c 0,0 0.0052,-0.006 0.01127,-0.001 l 0,0 0,0 0,0 c 0,0 -0.0052,0.006 -0.01127,0.001 z" id="path3641" style="fill:#be202e" />
     <path d="m -30.233189,292.45636 c 0,0 0.0052,-0.006 0.01127,-0.001 l 0,0 0,0 0,0 c 0,0 -0.0052,0.006 -0.01127,0.001 z" id="path3643" style="opacity:0.35;fill:#be202e" />
     <path d="m -30.233189,292.45636 c 0,0 0.0052,-0.006 0.01127,-0.001 l 0,0 0,0 0,0 c 0,0 -0.0052,0.006 -0.01127,0.001 z" id="path3654" style="fill:url(#SVGID_10_)" />
   </g>
   <text id="text3761" y="61.094482" x="290" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:40px;line-height:125%;font-family:Oswald;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" xml:space="preserve">
     <tspan y="61.094482" x="290" id="tspan3763">The</tspan>
   </text>
   <text id="text3416" y="72.094482" x="356" style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:57.5px;line-height:125%;font-family:Oswald;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" xml:space="preserve">
     <tspan y="72.094482" x="356" id="tspan3418">Apache Velocity Project</tspan>
   </text>
   <path id="path3557" d="m 897.15,23.54449 0,1.58889 3.72099,0 0,10.51111 1.72469,0 0,-10.51111 3.74815,0 0,-1.58889 -9.19383,0 z m 21.49753,0 -4.15555,8.44691 -4.18272,-8.44691 -2.07778,0 0,12.1 1.58889,0 0,-9.60123 4.11482,8.32469 1.1,0 4.11481,-8.32469 0,9.60123 1.58889,0 0,-12.1 -2.09136,0 z" style="fill:#6d6e71" />
   <text id="text3599" y="114.09448" x="400" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:35px;line-height:125%;font-family:Arial;text-align:start;letter-spacing:0.03em;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" xml:space="preserve">
     <tspan y="114.09448" x="400" id="tspan3601">http://velocity.apache.org/</tspan>
   </text>
 </svg>
 </a>

       </div>
       <div id="breadcrumb">
         <ul><li><a href="http://www.apache.org">apache</a></li><li><a href="/">velocity</a></li><li><a href="/engine/">engine</a></li><li><a href="/engine/2.1/">2.1</a></li><li><a href="#">vtl reference</a></li></ul>
       </div>
       <div id="middle">
         <div id="leftnav">

           <style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
 /*
  * Hide class="elementid-permalink", except when an enclosing heading
  * has the :hover property.
  */
 .headerlink, .elementid-permalink {
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <h2 id="velocity-engine">Velocity Engine<a class="headerlink" href="#velocity-engine" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="index.html">Welcome</a></li>
 <li><a href="overview.html">Overview</a></li>
 <li><a href="getting-started.html">Getting Started</a></li>
 <li><a href="webapps.html">Web Applications</a></li>
 <li><a href="/download.cgi#engine">Downloads</a></li>
 <li><a href="http://wiki.apache.org/velocity/VelocityFAQ">FAQ</a></li>
 </ul>
 <h2 id="docs">Docs<a class="headerlink" href="#docs" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="user-guide.html">User Guide</a></li>
 <li><a href="developer-guide.html">Developer Guide</a></li>
 <li><a href="vtl-reference.html">VTL Reference</a></li>
 <li><a href="configuration.html">Configuration</a></li>
 <li><a href="glossary.html">Glossary</a></li>
 <li><a href="apidocs/index.html">Javadoc</a></li>
 <li><a href="upgrading.html">Upgrading</a></li>
 </ul>
 <h2 id="developers">Developers<a class="headerlink" href="#developers" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="license.html">License</a></li>
 <li><a href="changes.html">Changes</a></li>
 <li><a href="dependencies.html">Dependencies</a></li>
 <li><a href="source-repository.html">Sources</a></li>
 <li><a href="build.html">Building</a></li>
 <li><a href="https://issues.apache.org/jira/browse/VELOCITY">Issues</a></li>
 <li><a href="http://wiki.apache.org/velocity/RoadMap">Road Map</a></li>
 <li><a href="http://wiki.apache.org/velocity/CodeStandards">Coding Standards</a></li>
 <li><a href="http://wiki.apache.org/velocity/DocumentationGuidelines">Doc Guidelines</a></li>
 </ul>
 <h2 id="community">Community<a class="headerlink" href="#community" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="http://wiki.apache.org/velocity/">Wiki</a></li>
 <li><a href="/news.html">News</a></li>
 <li><a href="http://wiki.apache.org/velocity/PoweredByVelocity">Powered by Velocity</a></li>
 <li><a href="http://wiki.apache.org/velocity/VelocityEditors">IDE/Editor Plugins</a></li>
 <li><a href="http://wiki.apache.org/velocity/PublishedArticlesAndBooks">Articles and Books</a></li>
 <li><a href="/contact.html">Mailing Lists</a></li>
 </ul>
 <h2 id="translations-outdated">Translations (outdated)<a class="headerlink" href="#translations-outdated" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="http://www.jajakarta.org/velocity/">Site (Japanese)</a></li>
 <li><a href="translations/user-guide_fi.html">User's Guide (Finnish)</a></li>
 <li><a href="translations/user-guide_fr.html">User's Guide (French)</a></li>
 <li><a href="translations/user-guide_es.html">User's Guide (Spanish)</a></li>
 </ul>

           <div id="bottom-nav">
             <img src="/images/pbv90x30.png"/>
             <div id="rss">
               <a class="poweredBy" href="/rss/news.rss" title="Velocity News Feed"><img class="poweredBy" alt="Velocity News Feed" src="/images/feed-icon-24x24.jpg"></a>
             </div>
             <iframe src="http://www.apache.org/ads/buttonbar.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="265"></iframe>
           </div>
         </div>
         <div id="content"><div class="section-content"><style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
 /*
  * Hide class="elementid-permalink", except when an enclosing heading
  * has the :hover property.
  */
 .headerlink, .elementid-permalink {
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <h2 id="vtl-reference-contents">VTL Reference - Contents<a class="headerlink" href="#vtl-reference-contents" title="Permanent link">&para;</a></h2>
 <div class="toc">
 <ul>
 <li><a href="#vtl-reference-contents">VTL Reference - Contents</a></li>
 <li><a href="#about-this-guide">About this Guide</a></li>
 <li><a href="#references">References</a><ul>
 <li><a href="#variables">Variables</a></li>
 <li><a href="#properties">Properties</a></li>
 <li><a href="#methods">Methods</a></li>
 </ul>
 </li>
 <li><a href="#directives">Directives</a><ul>
 <li><a href="#set-establishes-the-value-of-a-reference">#set - Establishes the value of a reference</a></li>
 <li><a href="#ifelseifelse-output-conditional-on-truth-of-statements">#if/#elseif/#else - Output conditional on truth of statements</a></li>
 <li><a href="#foreach-loops-through-a-list-of-objects">#foreach - Loops through a list of objects</a></li>
 <li><a href="#include-renders-local-files-that-are-not-parsed-by-velocity">#include - Renders local file(s) that are not parsed by Velocity</a></li>
 <li><a href="#parse-renders-a-local-template-that-is-parsed-by-velocity">#parse - Renders a local template that is parsed by Velocity</a></li>
 <li><a href="#stop-stops-the-template-engine">#stop - Stops the template engine</a></li>
 <li><a href="#break-stops-the-current-directive">#break - Stops the current directive</a></li>
 <li><a href="#evaluate-dynamically-evaluates-a-string-or-reference">#evaluate - Dynamically evaluates a string or reference</a></li>
 <li><a href="#define-assigns-a-block-of-vtl-to-a-reference">#define - Assigns a block of VTL to a reference</a></li>
 <li><a href="#macro-allows-users-to-define-a-velocimacro-vm-a-repeated-segment-of-a-vtl-template-as-required">#macro - Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required</a></li>
 </ul>
 </li>
 <li><a href="#comments">Comments</a><ul>
 <li><a href="#single-line-comments">Single Line Comments</a></li>
 <li><a href="#multi-line-comments">Multi Line Comments</a></li>
 </ul>
 </li>
 <li><a href="#unparsed-content">Unparsed Content</a></li>
 </ul>
 </div>
 <h2 id="about-this-guide">About this Guide<a class="headerlink" href="#about-this-guide" title="Permanent link">&para;</a></h2>
 <p>This guide is the reference for the Velocity Template Language (VTL). For more information, please also refer to the <a href="user-guide.html">Velocity User Guide</a>.</p>
 <p>Notations are given in a very approximative EBNF-like syntax, the goal is to remain readable.</p>
 <h2 id="references">References<a class="headerlink" href="#references" title="Permanent link">&para;</a></h2>
 <p>In the following syntax references, <em>identifier</em> refers to:</p>
 <p><span class="blue">(</span> <strong>a..z</strong> <span class="bigger blue">|</span> <strong>A..Z</strong> <span class="bigger blue">|</span> <strong>_</strong> <span class="blue">)</span> <span class="blue">[</span> <span class="blue">(</span> <strong>a..z</strong> <span class="bigger blue">|</span> <strong>A..Z</strong> <span class="bigger blue">|</span> <strong>0..9</strong> <span class="bigger blue">|</span> <strong>_</strong> <span class="blue">)</span> <span class="blue">,</span> <span class="blue">(</span> <strong>a..z</strong> <span class="bigger blue">|</span> <strong>A..Z</strong> <span class="bigger blue">|</span> <strong>0..9</strong> <span class="bigger blue">|</span> <strong>_</strong> <span class="blue">), ...</span> <span class="blue">]</span></p>
 <p>that is, a letter or an underscore followed by any number of letters, numbers and underscores.</p>
 <p>If the <code>parser.allows.dash.identifiers</code> configuration value is set to true, then the <strong>-</strong> dash is also allowed in identifiers (and must be surrounded by spaces to be interpreted as an arithmetic minus operator).</p>
 <h3 id="variables">Variables<a class="headerlink" href="#variables" title="Permanent link">&para;</a></h3>
 <p>Notation:</p>
 <p><strong>$</strong> <span class="blue">[</span> <strong>!</strong> <span class="blue">]</span> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <em>identifier</em> <span class="blue">[</span> <span class="blue">[</span> <strong>|</strong> <em>alternate value</em> <span class="blue">]</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <ul>
 <li><em>alternate value</em>: alternate expression to use if the reference is null, empty, false or zero</li>
 </ul>
 <p>Examples:</p>
 <ul>
 <li>Shorthand notation: <code>$mudSlinger_9</code></li>
 <li>Silent Shorthand notation: <code>$!mudSlinger_9</code></li>
 <li>Formal notation: <code>${mudSlinger_9}</code></li>
 <li>Silent Formal notation: <code>$!{mudSlinger_9}</code></li>
 <li>Alternate value: <code>${mudSlinger_9|$otherWheels}</code></li>
 </ul>
 <p><em>Note that for backward compatibility reasons, it's possible to enable '<strong><code>-</code></strong>' as a valid character in variables identifiers, <a href="configuration.html#parser-configuration">see the parser configuration section</a>.</em></p>
 <h3 id="properties">Properties<a class="headerlink" href="#properties" title="Permanent link">&para;</a></h3>
 <p>Notation:</p>
 <p><strong>$</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <em>identifier</em> <strong>.</strong> <em>identifier</em> <span class="blue">[</span> <span class="blue">[</span> <strong>|</strong> <em>alternate value</em> <span class="blue">]</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <ul>
 <li><em>alternate value</em>: alternate expression to use if the property is null, empty, false or zero</li>
 </ul>
 <p>Examples:</p>
 <ul>
 <li>Regular Notation: <code>$customer.Address</code></li>
 <li>Formal Notation: <code>${purchase.Total}</code></li>
 <li>Alternate Value: <code>${person.name|'John Doe'}</code></li>
 </ul>
 <h3 id="methods">Methods<a class="headerlink" href="#methods" title="Permanent link">&para;</a></h3>
 <p>Notation:</p>
 <p><strong>$</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <em>identifier</em> <strong>.</strong> <em>identifier</em> <strong>(</strong> <span class="blue">[</span> <em>parameter list...</em> <span class="blue">]</span> <strong>)</strong> <span class="blue">[</span> <span class="blue">[</span> <strong>|</strong> <em>alternate value</em> <span class="blue">]</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <ul>
 <li><em>alternate value</em>: alternate expression to use if the method returns null, empty, false or zero</li>
 <li><em>parameter list</em>: optional coma-separated list of expressions</li>
 </ul>
 <p>Examples:</p>
 <ul>
 <li>Regular Notation: <code>$customer.getAddress()</code></li>
 <li>Formal Notation: <code>${purchase.getTotal()}</code></li>
 <li>Regular Notation with Parameter List: <code>$page.setTitle( "My Home Page" )</code></li>
 <li>Alternate value: <code>${page.getTitle()|'Blank Page'}</code></li>
 </ul>
 <p>VTL Properties can be used as a shorthand notation for VTL Methods that take <em>get</em> and <em>set</em>. Either <em>$object.getMethod()</em> or <em>$object.setMethod()</em> can be abbreviated as <em>$object.Method</em>. 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.</p>
 <p>Each method argument can be any valid VTL expression.</p>
 <h2 id="directives">Directives<a class="headerlink" href="#directives" title="Permanent link">&para;</a></h2>
 <h3 id="set-establishes-the-value-of-a-reference">#set - Establishes the value of a reference<a class="headerlink" href="#set-establishes-the-value-of-a-reference" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>set</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>$ref</em> <strong>=</strong> <span class="blue">[</span> <strong>"</strong>, <strong>'</strong> <span class="blue">]</span> <em>arg</em> <span class="blue">[</span> <strong>"</strong>, <strong>'</strong> <span class="blue">]</span> )</p>
 <p>Usage:</p>
 <ul>
 <li><em>$ref</em> - The LHS of the assignment must be a variable reference or a property reference.</li>
 <li><em>arg</em> - The RHS of the assignment, <em>arg</em> is parsed (i.e. interpolated) if enclosed in double quotes, and not parsed if enclosed in single quotes.  If the RHS evaluates to <em>null</em>, it is <strong>not</strong> assigned to the LHS.</li>
 </ul>
 <p>Examples:</p>
 <ul>
 <li>Variable reference: <code>#set( $monkey = $bill )</code></li>
 <li>String literal: <code>#set( $monkey.Friend = 'monica' )</code></li>
 <li>Property reference: <code>#set( $monkey.Blame = $whitehouse.Leak )</code></li>
 <li>Method reference: <code>#set( $monkey.Plan = $spindoctor.weave($web) )</code></li>
 <li>Number literal: <code>#set( $monkey.Number = 123 )</code></li>
 <li>Range operator: <code>#set( $monkey.Numbers = [1..3] )</code></li>
 <li>Object list: <code>#set( $monkey.Say = ["Not", $my, "fault"] )</code></li>
 <li>Object map: <code>#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"})</code></li>
 </ul>
 <p>The RHS can also be a simple arithmetic expression, such as:</p>
 <ul>
 <li>Addition: <code>#set( $value = $foo + 1 )</code></li>
 <li>Subtraction: <code>#set( $value = $bar - 1 )</code></li>
 <li>Multiplication: <code>#set( $value = $foo * $bar )</code></li>
 <li>Division: <code>#set( $value = $foo / $bar )</code></li>
 <li>Remainder: <code>#set( $value = $foo % $bar )</code></li>
 </ul>
 <h3 id="ifelseifelse-output-conditional-on-truth-of-statements">#if/#elseif/#else - Output conditional on truth of statements<a class="headerlink" href="#ifelseifelse-output-conditional-on-truth-of-statements" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>if</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>condition</em> <strong>)</strong> <em>output</em> [<strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>elseif</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>condition</em> <strong>)</strong> <em>output</em> <span class="blue">]</span> <span class="blue">[</span> <strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>else</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span>  <em>output</em> <span class="blue">]</span> <strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>end</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <ul>
 <li>
 <p><em>condition</em> - Expression to evaluate. When its result is null, evaluate to false. Otherwise, check for conversion towards Boolean and non-emptiness as follow:</p>
 <ul>
 <li>return its value for a Boolean object, or the result of the getAsBoolean() method if it exists.</li>
 <li>if <code>directive.if.empty_check</code> = <code>false</code> (<code>true</code> by default), stop here and consider it true.</li>
 <li>return whether an array is empty.</li>
 <li>return whether isEmpty() is false (covers String and all Collection classes).</li>
 <li>return whether length() is zero (covers CharSequence classes other than String).</li>
 <li>returns whether size() is zero (covers all Collection classes).</li>
 <li>return whether a Number <em>strictly</em> equals zero.</li>
 <li>return whether the result of getAsString() is empty (and false for a null result) if it exists.</li>
 <li>return whether the result of getAsNumber() <em>strictly</em> equals zero (and false for a null result) if it exists.</li>
 <li>consider the condition is <code>true</code></li>
 </ul>
 </li>
 <li>
 <p><em>output</em> - May contain VTL.</p>
 </li>
 </ul>
 <p>Examples (showing different operators):</p>
 <table class="table">
 <thead>
 <tr>
 <th>Operator Name</th>
 <th>Symbol</th>
 <th>Alternative Symbol</th>
 <th>Example</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td>Equals Number</td>
 <td>==</td>
 <td>eq</td>
 <td><code>#if( $foo == 42 )</code></td>
 </tr>
 <tr>
 <td>Equals String</td>
 <td>==</td>
 <td>eq</td>
 <td><code>#if( $foo == "bar" )</code></td>
 </tr>
 <tr>
 <td>Object Equivalence</td>
 <td>==</td>
 <td>eq</td>
 <td><code>#if( $foo == $bar )</code></td>
 </tr>
 <tr>
 <td>Not Equals</td>
 <td>!=</td>
 <td>ne</td>
 <td><code>#if( $foo != $bar )</code></td>
 </tr>
 <tr>
 <td>Greater Than</td>
 <td>&gt;</td>
 <td>gt</td>
 <td><code>#if( $foo &gt; 42 )</code></td>
 </tr>
 <tr>
 <td>Less Than</td>
 <td>&lt;</td>
 <td>lt</td>
 <td><code>#if( $foo &lt; 42 )</code></td>
 </tr>
 <tr>
 <td>Greater Than or Equal To</td>
 <td>&gt;=</td>
 <td>ge</td>
 <td><code>#if( $foo &gt;= 42 )</code></td>
 </tr>
 <tr>
 <td>Less Than or Equal To</td>
 <td>&lt;=</td>
 <td>le</td>
 <td><code>#if( $foo &lt;= 42 )</code></td>
 </tr>
 <tr>
 <td>Boolean NOT</td>
 <td>!</td>
 <td>not</td>
 <td><code>#if( !$foo )</code></td>
 </tr>
 </tbody>
 </table>
 <p>Notes:</p>
 <ol>
 <li>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.</li>
 <li>You can also use brackets to delimit directives.  This is especially useful when text immediately follows an <code>#else</code> directive.<div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">($</span><span class="nv">foo</span> <span class="o">==</span> <span class="p">$</span><span class="nv">bar</span><span class="p">)</span><span class="x">it&#39;s true!</span><span class="cp">#{</span><span class="nf">else</span><span class="cp">}</span><span class="x">it&#39;s not!</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span>
 </pre></div>


 </li>
 </ol>
 <h3 id="foreach-loops-through-a-list-of-objects">#foreach - Loops through a list of objects<a class="headerlink" href="#foreach-loops-through-a-list-of-objects" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>foreach</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>$ref</em> <strong>in</strong> <em>arg</em> <strong>)</strong> <em>statements</em> <span class="blue">[</span> <strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>else</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <em>alternate statements</em> <span class="blue">]</span> <strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>end</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <ul>
 <li><em>$ref</em> - The first variable reference is the item.</li>
 <li><em>arg</em> - May be one of the following: a reference to a list (i.e. object array, collection, or map), an array list, or the range operator.</li>
 <li><em>statements</em> - What is output each time Velocity finds a valid item in the list denoted above as <em>arg</em>.  This output is any valid VTL and is rendered each iteration of the loop.</li>
 <li><em>alternate statements</em> - What is to display whenever Velocity did not enter the loop (when <em>arg</em> is null, empty, or doesn't have any valid iterator).</li>
 </ul>
 <p>Examples of the #foreach loop:</p>
 <ul>
 <li>Reference: <code>#foreach ( $item in $items ) $item #else no item #end</code></li>
 <li>Array list: <code>#foreach ( $item in ["Not", $my, "fault"] ) $item #end</code></li>
 <li>Range operator: <code>#foreach ( $item in [1..3] ) $item #end</code></li>
 </ul>
 <p>Inside the #foreach loop, the following can be used:</p>
 <ul>
 <li><code>$foreach.count</code> : 1-based loop index</li>
 <li><code>$foreach.index</code> : 0-based loop index</li>
 <li><code>$foreach.first</code> : true on the first iteration</li>
 <li><code>$foreach.last</code> : true on the last iteration</li>
 <li><code>$foreach.hasNext</code> : false on the last iteration</li>
 <li><code>$foreach.stop()</code> : exists the loop, synonym for <code>#break</code></li>
 </ul>
 <p>The maximum allowed number of loop iterations can be controlled engine-wide with <code>velocity.properties</code>. By default, there is no limit:</p>
 <div class="codehilite"><pre><span class="c"># The maximum allowed number of loops.</span>
 <span class="na">directive.foreach.max_loops</span> <span class="o">=</span> <span class="s">-1</span>
 </pre></div>


 <h3 id="include-renders-local-files-that-are-not-parsed-by-velocity">#include - Renders local file(s) that are not parsed by Velocity<a class="headerlink" href="#include-renders-local-files-that-are-not-parsed-by-velocity" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>include</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>arg</em> <span class="blue">[</span> <em>arg2</em>  ... <em>argn</em> <span class="blue">]</span> <strong>)</strong></p>
 <p>Usage:</p>
 <ul>
 <li><em>arg</em> - Refers to a valid file under TEMPLATE_ROOT.</li>
 </ul>
 <p>Examples:</p>
 <ul>
 <li>String: <code>#include( "disclaimer.txt"  "opinion.txt" )</code>+</li>
 <li>Variable: <code>#include( $foo  $bar )</code></li>
 </ul>
 <h3 id="parse-renders-a-local-template-that-is-parsed-by-velocity">#parse - Renders a local template that is parsed by Velocity<a class="headerlink" href="#parse-renders-a-local-template-that-is-parsed-by-velocity" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>parse</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>arg</em> <strong>)</strong></p></p>
 <p>Usage:</p>
 <ul>
 <li><em>arg</em> - Refers to a template under TEMPLATE_ROOT.</li>
 </ul>
 <p>Examples:</p>
 <ul>
 <li>String: <code>#parse( "lecorbusier.vm" )</code></li>
 <li>Variable: <code>#parse( $foo )</code></li>
 </ul>
 <p>Recursion permitted. See <em>directive.parse.max_depth</em> in <code>velocity.properties</code> to change from parse depth. (The default parse depth is 10.)</p>
 <h3 id="stop-stops-the-template-engine">#stop - Stops the template engine<a class="headerlink" href="#stop-stops-the-template-engine" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>stop</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <p>This will stop execution of the current template. This is good for debugging a template.</p>
 <h3 id="break-stops-the-current-directive">#break - Stops the current directive<a class="headerlink" href="#break-stops-the-current-directive" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>break</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span></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>
 <h3 id="evaluate-dynamically-evaluates-a-string-or-reference">#evaluate - Dynamically evaluates a string or reference<a class="headerlink" href="#evaluate-dynamically-evaluates-a-string-or-reference" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>evaluate</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>arg</em> <strong>)</strong></p>
 <p>Usage:</p>
 <ul>
 <li><em>arg</em> - String literal or reference to be dynamically evaluated.</li>
 </ul>
 <p>Examples:</p>
 <ul>
 <li>String: <code>#evaluate( 'string with VTL #if(true)will be displayed#end' )</code></li>
 <li>Variable: <code>#evaluate( $foo )</code></li>
 </ul>
 <h3 id="define-assigns-a-block-of-vtl-to-a-reference">#define - Assigns a block of VTL to a reference<a class="headerlink" href="#define-assigns-a-block-of-vtl-to-a-reference" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>define</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>$ref</em> <strong>)</strong> <em>statement</em> <strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>end</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <ul>
 <li><em>$ref</em> - Reference that is assigned the VTL block as a value.</li>
 <li><em>statement</em> - Statement that is assigned to the reference.</li>
 </ul>
 <p>Example:</p>
 <ul>
 <li><code>#define( $hello ) Hello $who #end #set( $who = "World!") $hello ## displays Hello World!</code></li>
 </ul>
 <h3 id="macro-allows-users-to-define-a-velocimacro-vm-a-repeated-segment-of-a-vtl-template-as-required">#macro - Allows users to define a Velocimacro (VM), a repeated segment of a VTL template, as required<a class="headerlink" href="#macro-allows-users-to-define-a-velocimacro-vm-a-repeated-segment-of-a-vtl-template-as-required" title="Permanent link">&para;</a></h3>
 <p>Format:</p>
 <p><strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>macro</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span> <strong>(</strong> <em>vmname</em> <em>$arg1</em> <span class="blue">[</span> <strong>=</strong> <em>def1</em> <span class="blue">]</span> <span class="blue">[</span> <em>$arg2</em> <span class="blue">[</span> <strong>=</strong> <em>def2</em> <span class="blue">]</span> <em>$arg3</em> <span class="blue">[</span> <strong>=</strong> def3 <span class="blue">]</span> ... <em>$argn</em> <span class="blue">[</span> <strong>=</strong> <em>defn</em> <span class="blue">]</span> ] <strong>)</strong> <span class="blue">[</span> <em>VTL code</em> <span class="blue">]</span> <strong>#</strong> <span class="blue">[</span> <strong>{</strong> <span class="blue">]</span> <strong>end</strong> <span class="blue">[</span> <strong>}</strong> <span class="blue">]</span></p>
 <p>Usage:</p>
 <ul>
 <li><em>vmname</em> - Name used to call the VM (<em>#vmname</em>)</li>
 <li><em>$arg1 $arg2</em> ... - 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.</li>
 <li><em>def1, def2, ...</em> - 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.</li>
 <li><em>VTL code</em> - Any valid VTL code, anything you can put into a template, can be put into a VM.</li>
 </ul>
 <p>Once defined, the VM is used like any other VTL directive in a template.</p>
 <div class="codehilite"><pre><span class="cp">#</span><span class="nf">vmname</span><span class="p">(</span> <span class="p">$</span><span class="nv">arg1</span> <span class="p">$</span><span class="nv">arg2</span> <span class="p">)</span><span class="x"></span>
 </pre></div>


 <p><strong>Except</strong>, that when you wish to call a VM with a body, then you must prefix the name of the VM with @.  The content of that body may be referenced in the macro definition via $!bodyContent as many or few times as you like.</p>
 <div class="codehilite"><pre><span class="err">#</span><span class="x">@vmname( </span><span class="p">$</span><span class="nv">arg1</span><span class="x"> </span><span class="p">$</span><span class="nv">arg2</span><span class="x"> ) here is the body</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span>
 </pre></div>


 <p>VMs can be defined in one of two places:</p>
 <ol>
 <li><em>Template library:</em> can be either VMs pre-packaged with Velocity or custom-made, user-defined, site-specific VMs; available from any template</li>
 <li><em>Inline:</em> found in regular templates, only usable when <em>velocimacro.permissions.allowInline=true</em> in <code>velocity.properties</code>.</li>
 </ol>
 <p>Since 2.0, when a macro argument is null or invalid, its rendering will display its local name. The following block of code:</p>
 <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">vmname</span> <span class="p">$</span><span class="nv">foo</span> <span class="p">)</span><span class="x"> </span><span class="p">$</span><span class="nv">foo</span><span class="x"> </span><span class="cp">#</span><span class="nf">end</span><span class="x"></span>
 <span class="cp">#</span><span class="nf">vmname</span><span class="p">(</span> <span class="p">$</span><span class="nv">null</span> <span class="p">)</span><span class="x"></span>
 </pre></div>


 <p>will display <code>$foo</code>. If you wish to revert to the 1.x behavior (which is to display <code>$null</code>), you can set the <code>velocimacro.preserve.arguments.literals</code> configuration property to true (since 2.1).</p>
 <h2 id="comments">Comments<a class="headerlink" href="#comments" title="Permanent link">&para;</a></h2>
 <p>Comments are not rendered at runtime.</p>
 <h3 id="single-line-comments">Single Line Comments<a class="headerlink" href="#single-line-comments" title="Permanent link">&para;</a></h3>
 <p>Example:</p>
 <div class="codehilite"><pre><span class="cp">##</span><span class="c"> This is a comment.**</span><span class="x"></span>
 </pre></div>


 <h3 id="multi-line-comments">Multi Line Comments<a class="headerlink" href="#multi-line-comments" title="Permanent link">&para;</a></h3>
 <p>Example:</p>
 <div class="codehilite"><pre><span class="cp">#</span><span class="c">*</span>
 <span class="c">  This is a multiline comment.</span>
 <span class="c">  This is the second line.</span>
 <span class="c">*</span><span class="cp">#</span><span class="x"></span>
 </pre></div>


 <h2 id="unparsed-content">Unparsed Content<a class="headerlink" href="#unparsed-content" title="Permanent link">&para;</a></h2>
 <p>Unparsed content is rendered at runtime, but is not parsed or interpreted.</p>
 <p>Example:</p>
 <div class="codehilite"><pre><span class="err">#</span><span class="x">[[</span>

 <span class="x">This has invalid syntax that would normally need </span>
 <span class="x">&quot;poor man&#39;s escaping&quot; like:</span>

 <span class="x"> - </span><span class="cp">#</span><span class="nf">define</span><span class="p">()</span><span class="x"></span>
 <span class="x"> - </span><span class="p">${</span><span class="nv">blah</span><span class="x"></span>

 <span class="x">]]</span><span class="err">#</span><span class="x"></span>
 </pre></div></div></div>
         <hr/>
         <div id="copyright">
           Copyright &#169; 2020 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
         </div>
       </div>
     </div>
   </body>
 </html>