Preprocessor

Preprocessor — плагин для Dokuwiki, который, как и следует из названия, производит предварительную обработку вики-текста, подобно тому, как работает препроцессор в си и си++.

Фактически, препроцессор — отдельный «слой» обработки текста в дополнение к вики-транслятору, никак с ним не связанный. Вся его работа заключается в том, чтобы итеративно сканировать текст в поисках специальных шаблонов, и преобразовывать их.

Синтаксис

Шаблон преобразователя имеет следующий вид:

${function|parameter|parameter…}

Его элементы имеют следующее значение:

${ (знак доллара + открывающая фигурная скобка)
Эти два символа предваряют шаблон
function
Имя функции, возможно, с символами-модификаторами.
| (вертикальная черта)
Символ разделителя. Этот символ отделяет название функции от параметров и параметры друг от друга.
parameter
Набор параметров функции. Их может быть от нуля и больше, это определяется функцией, которая будет обрабатывать шаблон.
} (закрывающая фигурная скобка)
Этот символ ставится за последним параметром функции, обозначая конец шаблона.

Некоторые функции могут принимать параметры с ключами в этом случае параметр имеет такой вид:

key=value

Следует заметить, что препроцессор обрабатывает пробелы точно также, как любые другие символы, и поэтому их не следует ставить где попало. Так, не следует ставить пробел между скобкой и названием функции или ключом и знаком равно.

Экранирование

Может случиться так, что необходимо избежать интерпретации символов препроцессором. К примеру, если небходмио вставить код шаблона в текст, или передать символы в качестве параметров. Для этого в интерпретатор введена возможность экранирования управляющих символов. Для этого служит символ экранирования — \ (обратная косая черта), который, будучи поставленным перед символом $, {, | или } отменяет его синтаксический смысл, требуя его интерпретировать как обычный текст. При этом в процессе интерпретации (в качестве параметра или выходного текста).

Таким образом, на месте вики-текста \${dt}, будет просто выведен текст «${dt}», а не подставлено значение функции dt. Точно также любой из этих символов можно подставить в качестве параметра, однако следует заметить, что если параметр шаблона попадает в выходной текст, то, так как он будет обрабатываться дважды (в качестве параметра и в качестве подставленного на выход препроцессора текста, то, возможно, его потребуется экранировать дважды.

Препроцессор также автоматически экранирует вложенные парные фигурные скобки и чёрточки внутри них. То есть, в конструкции типа:

${function|{abc|def}|gh}

чёрточка перед def не будет разделителем параметров, а скобка после — не закроет шаблон, т. е. будет {abc|def} передстся как первый параметр, gh — как второй. Экранирующие скобки можут также вкладываться, то есть в качетсве параметра может быть {abc|{def}}, def, и даже abc|def}}}}}}. Главное, чтобы соблюдался баланс скобок — каждой открывающей скобке соответствовала своя закрывающая. Если же необходимы непарные скобки, они экранируются обычным образом. ==== Вложенные шаблоны ==== Препроцессор производит итеративную обработку текста, до тех пор, пока в нём не останется интерпретируемых шаблонов. То есть, после обработки шаблона, его результат вновь поступает на интерпретацию в качестве исходного текста на следующей итерации. При этом обработка идёт по принципу «начиная с самого внутреннего», то есть всегода интерпретируется шаблон, не имеющий вложенных в себя. Это значит следующее — в конструкции типа : ${a|${b|${c}}} первым будет обрабатываться функция с, затем его результат будет подставлен в функцию b, и уже этот результат будет подставлен в функцию a.

Важным моментом, упомянутым в предыдущем разделе является то, что «разэкранирование» происходит при каждой обработке параметров и при конечной обработке текста. Поэтому, при простом использовании шаблона может потребоваться двукратное экранирование (\\), при одном вложении — трёхкратное (\\\), и так далее. При этом следует особенно следить за символами | и } — при появлении первого во вложенном шаблоне, он, не будучи экранированным, окажется разделителем разбив результат на несколько параметров (что может оказаться неожиданным), а второй без открывающей пары может неявно закрыть шаблон.

Экранирование также позволяет менять порядок обработки шаблонов. Заэкранированный один раз вложенный шаблон не будет развёрнут до окружающего его, а после, оказавшись в результате разворачивания, дважды экранированный — после развёртывания второго вложения, и т. д.

Вот, в качестве примера, дазличные способы последовательного разворачивания и экранирования:

${a|${b}} b, затем a
${a|\${b}} a, затем b
${a|\\${b}} только a, b вообще не будет развёрнут
\${a|${b}} только b, a вообще не будет развёрнут
\${a|\${b}} ни a, ни b не будут развёрнуты

Функции

dt --- дата и время

Синтаксис:

${dt|date|format}

with --- подстановка набора значений по шаблону

Синтаксис:

${with|template|value|value…}

count --- счётчик

Синтаксис:

${count|to|from|by}

eval --- вычисление и выбор

Синтаксис:

Простое вычисление
${eval|expression}
Вычисление и выбор
${eval|expression|option|option…|default}
Вычисление и выбор (способ с ключами)
${eval*|expression|value=option|value=option…|default}

regsub --- подстановка по регулярному выражению

Синтаксис:

${regsub|pattern|replacement|data}

Разработка новых функций

set/preprocessor.txt · Последние изменения: 2010/08/17 01:46 — vovanium
За исключением случаев, когда указано иное, содержимое этой вики предоставляется на условиях следующей лицензии: CC Attribution 3.0 Unported