用户定义的指令(<@...>)

Page Contents

Synopsis

<@user_def_dir_exp param1=val1 param2=val2 ... paramN=valN/>
(Note the XML-style / before the >)
or if you need loop variables (more details...)
<@user_def_dir_exp param1=val1 param2=val2 ... paramN=valN ; lv1, lv2, ..., lvN/>

Or the same as the above two but with end-tag (more details...):

<@user_def_dir_exp ...>
  ...
</@user_def_dir_exp>
or
<@user_def_dir_exp ...>
  ...
</@>

Or all above but with positional parameter passing (more details...):

<@user val1, val2, ..., valN/>
...etc.

Where:

user_def_dir_exp：表达式的结果为用户定义的指令(例如宏)，该指令将被调用。
param1，param2，...等：参数名称。它们不是*表达式。
val1，val2，...等：参数的值。它们是表达式。
lv1，lv2，...等：loop variables的名称。它们不是*表达式。

参数的数量可以为 0(即无参数)。

参数的 Sequences 并不重要(除非您使用位置参数传递)。参数名称必须唯一。参数名称中的小写字母和大写字母被认为是不同的字母(即Color和color不相同)。

Description

这将调用用户定义的指令，例如宏。参数的含义以及所支持和必需的参数集取决于具体的用户定义指令。

您可以阅读关于用户定义指令的教程。

示例 1：调用存储在变量html_escape中的指令：

<@html_escape>
  a < b
  Romeo & Juliet
</@html_escape>

Output:

a &lt; b
  Romeo &amp; Juliet

示例 2：调用带有参数的宏：

<@list items=["mouse", "elephant", "python"] title="Animals"/>
...
<#macro list title items>
  <p>${title?cap_first}:
  <ul>
    <#list items as x>
      <li>${x?cap_first}
    </#list>
  </ul>
</#macro>

Output:

<p>Animals:
  <ul>
      <li>Mouse
      <li>Elephant
      <li>Python
  </ul>

...

End-tag

您可以在end-tag中省略user_def_dir_exp。也就是说，您始终可以写</@>而不是</@anything>。当user_def_dir_exp表达式过于复杂时，此规则最有用，因为您不必在 end-tag 中重复该表达式。此外，如果表达式不包含简单变量名和点，则不允许重复该表达式。例如，<@a_hash[a_method()]>...</@a_hash[a_method()]>是错误；您必须写<@a_hash[a_method()]>...</@>。但是<@a_hash.foo>...</@a_hash.foo>可以。

还有一条特殊的规则说，如果user_def_dir_exp以?with_args(...)结尾，那么当匹配结束标签时，它将被忽略，因此您可以编写<@myMacro?with_args(args)>...</@myMacro>之类的东西。

Loop variables

一些用户定义的指令创建循环变量(类似于list指令)。与 sched 义的指令(如list)一样，调用指令时会给出循环变量的名称(如<#list foos as foo>...</#list>中的foo)，而变量的* value *由指令本身设置。对于用户定义的指令，语法为：循环变量的名称以分号结尾。例如：

<@myRepeatMacro count=4 ; x, last>
  ${x}. Something... <#if last> This was the last!</#if>
</@myRepeatMacro>

请注意，由用户定义的指令创建的循环变量的数量和在分号后指定的循环变量的数量不必匹配。说，如果您对重复是否是最后一次不感兴趣，可以简单地写：

<@myRepeatMacro count=4 ; x>
  ${x}. Something...
</@myRepeatMacro>

或者您甚至可以：

<@myRepeatMacro count=4>
  Something...
</@myRepeatMacro>

此外，如果在分号后指定的循环变量多于用户定义的指令创建的循环变量，则不会导致错误，只会创建最后几个循环变量(即在嵌套内容中未定义的循环变量)。但是，尝试使用未定义的循环变量将导致错误(除非您使用诸如?default的内置变量)，因为您尝试访问不存在的变量。

有关更多说明，请参见关于用户定义指令的教程。

位置参数传递