ru config tags

Настройки тегов

Второй необязательный аргумент конструктора Parser получает массив $tags. С помощью этого массива можно расширить стандартный синтаксис, добавив свои теги или изменив настройки существующих.

$options = [
    // ...
];

$tags = [
    'br' => null,
    'hr' => 'HtmlTag',
    'code' => [
        'options' => ['default_lang' => 'javascript'],
    ],
    'php' => [
        'classname' => '=code',
        'options' => ['lang' => true],
    ],
];

$parser = new Parser($options, $tags);

В примере мы сделали следующее:

• Удалили совсем тег [BR].
• Добавили тег [HR] для вставки <hr>.
• Указали тегу [CODE], что если не указан язык кода, то по умолчанию использовать JavaScript.
• Создали тег [PHP], аналогичный [CODE], но предназначенный для вывода только php-кода.

Формат массива $tags

Ключ - имя тега (в нижнем регистре). Значение - его параметры (см. ниже).

Если тег с таким именем уже существует - значит меняем его настройки. Если не существует - добавляем свой.

Специальные имена

Кроме того существуют следующие специальные имена тегов:

• / - соответствует закрывающему тегу ([/B], [/TABLE] и т.п.).
• `` (пустое имя) - соответствует тегу без имени.

Тег без имени, например [<script></script>] обрабатывается также, как и [HTML] (см. здесь). Можно обрабатывать его аналогично другому тегу:

$parser = new Parser(null, [
    '' => 'Code',
]);

Теперь подобные вставки считаются не HTML, а вставками форматированного кода.

Параметры тега

Значения элементов массива $tags описывают поведение указанного тега. В полном формате они представляют собой ассоциативный массив со следующими полями:

• classname - имя класса или алиас.
• options - массив настроек.
• name - имя тега.

Все поля необязательны. Если нужен только classname, то можно вместо массива указывать просто строку. Например:

$tags = [
    'mytag' => '\my\ns\Tag',
];

Аналогично:

$tags = [
    'mytag' => [
        'classname' => '\my\ns\Tag',
        'options' => [],
        'name' => null,
    ];
];

classname

Этот параметр может содержать:

• Имя класса, отвечающего за тег.
• Алиас на существующий тег в виде =alias (см. ниже).

Имя класса может быть полным и должно начинаться с \ (\my\ns\Tag).

Имя класса не начинающегося с \ отсчитывается от пространства имён axy\ml\tags, то есть это стандартные теги. Например Code - axy\ml\tags\Code.

options

Массив настроек тега. Структура зависит от самого тега.

Если это новый тег, то как использовать настройки см. раздел написание своих тегов.

Если существующий или алиас, то настройки позволяют изменить его поведение. Списки настроек существующих тегов приведены в соответствующем разделе.

name

name требует определения в редких случаях, которые описаны ниже.

Удаление тега

Существующий тег можно удалить, указав в качестве параметров NULL:

$tags = [
    'br' => null,
];

Теперь тег [BR] будет игнорироваться, а в логи будет писаться ошибка.

Написание своего тега

Новый тег создаётся так:

• Читаем раздел написание своих тегов.
• Создаём класс тега, например, my\ns\Tag.
• Добавляем его в список:

$tags = [
    'mytag' => '\my\ns\Tag`,
];

Либо, если нужны настройки:

$tags = [
    'mytag' => [
        'classname' => '\my\ns\Tag`,
        'options' => [
            'opt1' => 'value 1',
            'opt2' => 'value 2',
        ],
    ],
];

Теперь в документах доступен тег [MyTag].

Использование стандартных классов для создания тегов

Во многих случаях можно не писать новый класс, а использовать стандартный.

Например, класс HtmlTag используется для тегов-аналогов HTML-тегов, таких как [B], [I] и т.п.

Можно просто добавит аналогичных тегов:

$tags = [
    'abbr' => 'HtmlTag',
    'strong' => 'HtmlTag',
    'hr' => [
        'classname' => 'HtmlTag',
        'options' => ['single' => true],
    ],
];

Добавили теги [ABBR], [STRONG] и [HR] для вывода <abbr>, <strong> и <hr />. Для [HR] указали, что это одиночный тег и его следует закрывать с помощью />.

Также, класс Scheme отвечает за теги [HTTP] и [HTTPS]. Просто берёт имя класса в качестве схемы урла, а остальную часть тега в качестве остальной части урла.

Добавляем протокол ftp:

$tags = [
    'ftp' => 'Scheme',
];

Теперь можно вставлять ftp-ссылки: [ftp://server.loc/] или [ftp://server.loc/ ссылка].

Алиасы и использование name

classname начинающийся с = является алиасом на другой тег.

$tags = [
    'c' => '=code',
    'php' => [
        'classname' => '=c',
        'options' => ['lang' => 'php'],
    ],
];

Теперь тег [c] становится краткой записью для [code]. Можно писать так: [c: $x = 2 + 3;].

Можно также указывать опции. Тег [php] не только является алиасом для [code], но и для него установлены собственные настройки.

Заметьте, что можно ставить алиасы на алиасы. Только следует избегать рекурсии.

name тега

Важное отличие указания существующего класса от установки алиаса: в первом случае обрабатывающему классу передаётся имя нового тега, а во втором имя того, на который указывает алиас.

$tags = [
    'hr' => 'HtmlTag',
    'strong' => '=b',
];

Класс HtmlTag обрабатывает полученное имя тега. В случае с [HR] он получает имя hr и результат - <hr>.

В случае со [STRONG] ему приходит b и результат - <b>.

Получаемое классом имя тега можно указать явно:

$tags = [
    'line' => [
        'classname' => 'HtmlTag',
        'name' => 'hr',
        'options' => ['single' => true],
    ],
];

Теперь тег [LINE] заменяется на <hr />.

Настройки стандартных тегов

Стандартные теги можно настраивать, указав им массив options.

$tags = [
    'code' => [
        'options' => [
            'default_lang' => 'php',
        ],
    ],
];

Теперь если у [CODE] не указан атрибут с языком, используется php.

Полный список стандартных классов и возможных настроек приведён в соответствующем разделе.

Можно, конечно, заменить и сам отвечающий за тег класс:

$tags = [
    'code' => '\my\ns\MyCodeTag',
];