README

Lex 是一个轻量级模板解析器。

本项目是从 https://github.com/pyrocms/lex 分离出来的分支。

Lex 在 MIT 许可证下发布，版权所有 2011 - 2014 PyroCMS 团队。

基本用法

使用 Lex

Lex 是一个名为 pyrocms/lex 的 Composer 包。要使用它，只需将其添加到您的 composer.json 文件的 require 部分。

{
    "require": {
        "pyrocms/lex": "2.2.*"
    }
}

在您的 composer.json 文件中添加 Lex 之后，只需像平常一样使用类。

$parser = new Lex\Parser();

使用 Lex

基本文件解析

$parser = new Lex\Parser();
$template = $parser->parse(file_get_contents('template.lex'), $data);

您还可以设置作用域粘合剂（请参阅下面的“作用域粘合剂”）

$parser = new Lex\Parser();
$parser->scopeGlue(':');
$template = $parser->parse(file_get_contents('template.lex'), $data);

要允许无解析提取累积，以便它们不会被解析器后续调用解析，请将 cumulativeNoparse 设置为 true

$parser = new Lex\Parser();
$parser->cumulativeNoparse(true);
$template = $parser->parse(file_get_contents('template.lex'), $data);
// Second parse on the same text somewhere else in your app
$template = $parser->parse($template, $data);
// Now that all parsing is done we inject the contents between the {{ noparse }} tags back into the template text
Lex\Parser::injectNoparse($template);

如果您只想解析数据数组，而无需关注回调标签或注释，可以使用 parseVariables() 方法

$parser = new Lex\Parser();
$template = $parser->parseVariables(file_get_contents('template.lex'), $data);

模板中的 PHP

默认情况下，PHP 被编码，而不是执行。这是出于安全考虑。但是，有时您可能想启用它。要做到这一点，只需将 true 作为 parse() 调用的第四个参数发送。

$parser = new Lex\Parser();
$template = $parser->parse(file_get_contents('template.lex'), $data, $callback, true);

语法

一般

所有 Lex 代码都由双大括号（{{ }}）分隔。这些分隔符被选择以减少与 JavaScript 和 CSS 冲突的可能性。

以下是一些 Lex 模板代码的示例

Hello, {{name}}

作用域粘合剂

作用域粘合剂是 Lex 用来触发作用域更改的字符。作用域更改发生在，例如，您在数组/对象内部访问嵌套变量时，或者当定义自定义回调标签时。

默认情况下，使用点（.）作为作用域粘合剂，尽管您可以选择任何字符。

设置作用域粘合剂

$parser->scopeGlue(':');

空白

允许在分隔符前后添加空白，但是在某些情况下，标签内的空白是禁止的（以下各节中解释）。

一些有效示例

{{ name }}
{{name }}
{{ name}}
{{  name  }}
{{
  name
}}

一些无效示例

{{ na me }}
{ {name} }

注释

您可以通过将文本包装在 {{# #}} 中来为模板添加注释。

示例

{{# This will not be parsed or shown in the resulting HTML #}}

{{#
    They can be multi-line too.
#}}

防止解析

您可以通过将代码包装在 {{ noparse }}{{ /noparse }} 标签中来防止解析器解析代码块。

示例

{{ noparse }}
    Hello, {{ name }}!
{{ /noparse }}

变量标签

在处理变量时，您可以使用：访问单个变量、访问数组/对象内部嵌套的变量，以及遍历数组。您甚至可以遍历嵌套数组。

简单变量标签

在我们的基本示例中，让我们假设您有以下变量数组（发送给解析器）

array(
    'title'     => 'Lex is Awesome!',
    'name'      => 'World',
    'real_name' => array(
        'first' => 'Lex',
        'last'  => 'Luther',
    )
)

基本示例

{{# Parsed: Hello, World! #}}
Hello, {{ name }}!

{{# Parsed: <h1>Lex is Awesome!</h1> #}}
<h1>{{ title }}</h1>

{{# Parsed: My real name is Lex Luther!</h1> #}}
My real name is {{ real_name.first }} {{ real_name.last }}

{{ real_name.first }} 和 {{ real_name.last }} 标签检查 real_name 是否存在，然后检查 first 和 last 分别是否存在于 real_name 数组/对象内部，然后返回它。

循环变量标签

循环变量标签与简单变量标签类似，但它们对应于数组数组的数组/对象，这些数组会被遍历。

循环变量标签是一个闭合标签，它包装循环内容。关闭标签必须与打开标签完全匹配，除了它必须以前缀斜杠（/）为前缀。斜杠和标签名之间不能有空格（斜杠前面的空格是允许的）。

有效示例

{{ projects }} Some Content Here {{ /projects }}

无效示例

{{ projects }} Some Content Here {{/ projects }}

循环内容是打开和关闭标签之间的内容。这个内容会遍历并输出循环数组中的每个项目。

在循环标签中，您可以访问循环中当前元素的任何子变量。

以下示例中，假设您有以下数组/对象变量

array(
    'title'     => 'Current Projects',
    'projects'  => array(
        array(
            'name' => 'Acme Site',
            'assignees' => array(
                array('name' => 'Dan'),
                array('name' => 'Phil'),
            ),
        ),
        array(
            'name' => 'Lex',
            'contributors' => array(
                array('name' => 'Dan'),
                array('name' => 'Ziggy'),
				array('name' => 'Jerel')
            ),
        ),
    ),
)

在模板中，我们将想显示标题，然后是项目及其分配者列表。

<h1>{{ title }}</h1>
{{ projects }}
    <h3>{{ name }}</h3>
    <h4>Assignees</h4>
    <ul>
    {{ assignees }}
        <li>{{ name }}</li>
    {{ /assignees }}
    </ul>
{{ /projects }}

如您所见，在每个项目元素内部，我们可以访问该项目的分配者。您也可以看到，您可以像任何其他数组一样遍历子值。

条件语句

Lex中的条件语句简单易用。它允许使用标准的if、elseif和else，但也增加了unless和elseunless。

unless和elseunless与使用{{ if ! (expression) }}和{{ elseif ! (expression) }}完全相同。它们是添加的更简洁、更易于理解的语法。

所有if块都必须使用{{ endif }}标签关闭。

在if条件语句内部的变量，不应使用标签定界符（这会导致输出中出现奇怪的问题）。

条件语句可以包含您在PHP中使用的任何比较运算符（==、!=、===、!==、>、<、<=、>=）。您还可以使用任何逻辑运算符（!、not、||、&&、and、or）。

示例

{{ if show_name }}
    <p>My name is {{real_name.first}} {{real_name.last}}</p>
{{ endif }}

{{ if user.group == 'admin' }}
    <p>You are an Admin!</p>
{{ elseif user.group == 'user' }}
    <p>You are a normal User.</p>
{{ else }}
    <p>I don't know what you are.</p>
{{ endif }}

{{ if show_real_name }}
    <p>My name is {{real_name.first}} {{real_name.last}}</p>
{{ else }}
    <p>My name is John Doe</p>
{{ endif }}

{{ unless age > 21 }}
    <p>You are to young.</p>
{{ elseunless age < 80 }}
    <p>You are to old...it'll kill ya!</p>
{{ else }}
    <p>Go ahead and drink!</p>
{{ endif }}

not运算符

not运算符等同于使用!运算符。它们可以完全互换（实际上，not在编译前被转换为!）。

条件语句中的未定义变量

条件语句中的未定义变量将被评估为null。这意味着您可以执行类似{{ if foo }}的操作，而不必担心变量是否已定义。

检查变量是否存在

要检查条件语句中的变量是否存在，您使用exists关键字。

示例

{{ if exists foo }}
    Foo Exists
{{ elseif not exists foo }}
    Foo Does Not Exist
{{ endif }}

您还可以将其与其他条件结合使用

{{ if exists foo and foo !== 'bar' }}
    Something here
{{ endif }}

表达式exists foo评估为true或false。因此，以下这样的操作也是可行的

{{ if exists foo == false }}
{{ endif }}

条件语句中的回调标签

在条件语句中使用回调标签很简单。就像使用任何其他变量一样使用它，只有一个例外。当您需要为回调标签提供属性时，您必须用单个大括号括起来（您可以选择为所有回调标签使用它们）。

注意：当在条件语句中使用大括号时，在大括号之后不能有任何空白，或在大括号之前的回调标签内不能有空白。这样做会导致错误。

示例

{{ if user.logged_in }} {{ endif }}

{{ if user.logged_in and {user.is_group group="admin"} }} {{ endif }}

回调标签

回调标签允许您拥有具有通过回调发送的属性的标签。这使得创建一个良好的插件系统变得容易。

以下是一个示例

{{ template.partial name="navigation" }}

您还可以关闭标签，使其成为回调块

{{ template.partial name="navigation" }}
{{ /template.partial }}

请注意，属性不是必需的。当没有提供属性时，标签将首先被检查是否为数据变量，然后作为回调执行。

{{ template.partial }}

回调

回调可以是任何有效的PHP可调用函数。它作为第三个参数发送到parse()方法。

$parser->parse(file_get_contents('template.lex'), $data, 'my_callback');

回调必须接受以下3个参数（按此顺序）

$name - The name of the callback tag (it would be "template.partial" in the above examples)
$attributes - An associative array of the attributes set
$content - If it the tag is a block tag, it will be the content contained, else a blank string

回调必须返回一个字符串，这将替换内容中的标签。

示例

function my_callback($name, $attributes, $content)
{
    // Do something useful
    return $result;
}

关闭回调标签

如果回调标签可以用单或块形式使用，那么在以单形式使用时，它必须关闭（就像HTML一样）。

示例

{{ foo.bar.baz }}{{ /foo.bar.baz }}

{{ foo.bar.baz }}
    Content
{{ /foo.bar.baz }}

自闭合回调标签

您可以使用自闭合标签来缩短上述代码，就像在HTML中一样。只需在标签末尾放置一个 /（/ 和 }} 之间不能有空格）。

示例

{{ foo.bar.baz /}}

{{ foo.bar.baz }}
    Content
{{ /foo.bar.baz }}

递归回调块

递归回调标签允许您使用与主块相同的输出循环遍历子元素。这通过使用与数组键名一起的 recursive 关键字来实现。这两个词必须像下面示例中那样用星号包围。

示例

function my_callback($name, $attributes, $content)
{
	$data = array(
			'url' 		=> 'url_1',
			'title' 	=> 'First Title',
			'children'	=> array(
				array(
					'url' 		=> 'url_2',
					'title'		=> 'Second Title',
					'children' 	=> array(
						array(
							'url' 	=> 'url_3',
							'title'	=> 'Third Title'
						)
					)
				),
				array(
					'url'		=> 'url_4',
					'title'		=> 'Fourth Title',
					'children'	=> array(
						array(
							'url' 	=> 'url_5',
							'title'	=> 'Fifth Title'
						)
					)
				)
			)
	);

	$parser = new Lex\Parser();
	return $parser->parse($content, $data);
}

在模板中按以下方式设置。如果 children 不为空，Lex 将对 children 数组中的每个元素再次解析 {{ navigation }} 标签之间的内容。然后，生成的文本将插入到 {{ *recursive children* }} 的位置。这可以做到多层嵌套。

<ul>
	{{ navigation }}
		<li><a href="{{ url }}">{{ title }}</a>
			{{ if children }}
				<ul>
					{{ *recursive children* }}
				</ul>
			{{ endif }}
		</li>
	{{ /navigation }}
</ul>

结果

<ul>
	<li><a href="url_1">First Title</a>
		<ul>
			<li><a href="url_2">Second Title</a>
				<ul>
					<li><a href="url_3">Third Title</a></li>
				</ul>
			</li>

			<li><a href="url_4">Fourth Title</a>
				<ul>
					<li><a href="url_5">Fifth Title</a></li>
				</ul>
			</li>
		</ul>
	</li>
</ul>