Preprocessor — плагин для Dokuwiki, который, как и следует из названия, производит предварительную обработку вики-текста, подобно тому, как работает препроцессор в си и си++.
Фактически, препроцессор — отдельный «слой» обработки текста в дополнение к вики-транслятору, никак с ним не связанный. Вся его работа заключается в том, чтобы итеративно сканировать текст в поисках специальных шаблонов, и преобразовывать их.
Шаблон преобразователя имеет следующий вид:
$
{function|parameter|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|date|format}
Синтаксис:
$
{with|template|value|value…}
Синтаксис:
$
{count|to|from|by}
Синтаксис:
$
{eval|expression}
$
{eval|expression|option|option…|default}
$
{eval*|expression|value=option|value=option…|default}
Синтаксис:
$
{regsub|pattern|replacement|data}