Памятка по командам Latex 3

Краткий справочник по командам LAtex 3 для создания собственных команд и окружения

Краткая таблица с основными типами аргументов и их описанием:

| Ключ | Краткое описание                                                                 |
|------|----------------------------------------------------------------------------------|
| **m**  | Обычный обязательный аргумент (один токен или `{...}`).                          |
| **r**  | Обязательный аргумент с разделителями (формат: `r⟨t1⟩⟨t2⟩`).                     |
| **R**  | Как `r`, но с значением по умолчанию (формат: `R⟨t1⟩⟨t2⟩{⟨default⟩}`).          |
| **v**  | Дословный аргумент (аналог `\verb` в LaTeX).                                   |
| **b**  | Тело окружения (только для `\begin{...}...\end{...}`).                         |
| **o**  | Необязательный аргумент в `[...]`, возвращает `-NoValue-` если отсутствует.     |
| **d**  | Необязательный аргумент с разделителями (формат: `d⟨t1⟩⟨t2⟩`).                 |
| **O**  | Как `o`, но с значением по умолчанию (формат: `O{⟨default⟩}`).                 |
| **D**  | Как `d`, но с значением по умолчанию (формат: `D⟨t1⟩⟨t2⟩{⟨default⟩}`).         |
| **s**  | Необязательная звезда (`*`), возвращает `\BooleanTrue`/`\BooleanFalse`.        |
| **t**  | Необязательный токен (формат: `t⟨token⟩`), возвращает `\BooleanTrue`/`False`.  |
| **e**  | Необязательные "украшения" (формат: `e{⟨tokens⟩}`), возвращает `-NoValue-`.    |
| **E**  | Как `e`, но с значениями по умолчанию (формат: `E{⟨tokens⟩}{⟨defaults⟩}`).     |
| **+**  | Модификатор: делает аргумент "длинным" (параграфным).                           |
| **!**  | Модификатор: управляет пробелами перед необязательными аргументами.             |
| **=**  | Модификатор: аргумент интерпретируется как ключ-значение (keyvals).             |
| **>**  | Модификатор: применяет "процессор аргументов" для преобразования ввода.        |

Создание команд документа

\NewDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\RenewDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\ProvideDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\DeclareDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}

Эта группа команд используется для создания команды ⟨cmd⟩. Спецификация аргумента для функции задается с помощью ⟨arg spec⟩, а команда использует ⟨code⟩, где #1, #2 и т. д. заменяются на аргументы, найденные парсером.

Пример:

\NewDocumentCommand\chapter{s o m} {
  \IfBooleanTF{#1}
    {\typesetstarchapter{#3}}
    {\typesetnormalchapter{#2}{#3}}
}

Создание окружений документа

\NewDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\RenewDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\ProvideDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\DeclareDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}

Эти команды работают так же, как \NewDocumentCommand и т. д., но создают окружения (\begin{⟨env⟩} … \end{⟨env⟩}). Как ⟨beg-code⟩, так и ⟨end-code⟩ могут получать доступ к аргументам, как определено в ⟨arg spec⟩. Аргументы будут переданы после \begin{⟨env⟩}. Все пробелы в начале и в конце {⟨env⟩} удаляются перед определением, таким образом:

Проверка специальных значений

\IfNoValueTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfNoValueT {⟨arg⟩} {⟨true code⟩}
\IfNoValueF {⟨arg⟩} {⟨false code⟩}

Команды \IfNoValue(TF) используются для проверки, является ли ⟨argument⟩ (#1, #2 и т. д.) специальным маркером -NoValue-. Например:

\NewDocumentCommand\foo{o m} {
  \IfNoValueTF {#1}
    {\DoSomethingJustWithMandatoryArgument{#2}}
    {\DoSomethingWithBothArguments{#1}{#2}}
}

\IfValueTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfValueT {⟨arg⟩} {⟨true code⟩}
\IfValueF {⟨arg⟩} {⟨false code⟩}

Обратная форма тестов \IfNoValue(TF) также доступна как \IfValue(TF). Контекст определит, какая логическая форма имеет наибольший смысл для данного сценария кода.

\IfBlankTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfBlankT {⟨arg⟩} {⟨true code⟩}
\IfBlankF {⟨arg⟩} {⟨false code⟩}

Таблица описывающая команды проверки специальных значений:

| Команда                     | Краткое описание                                                                 |
|-----------------------------|----------------------------------------------------------------------------------|
| `\BooleanFalse`             | Логическое значение "ложь" (используется с аргументами `s`/`t`).                |
| `\BooleanTrue`              | Логическое значение "истина" (используется с аргументами `s`/`t`).              |
| `\IfBooleanTF{arg}{true}{false}` | Проверяет, является ли `arg` булевым значением (`\BooleanTrue`/`\BooleanFalse`). |
| `\IfBooleanT{arg}{true}`    | Выполняет `true` код, если `arg` равно `\BooleanTrue`.                          |
| `\IfBooleanF{arg}{false}`   | Выполняет `false` код, если `arg` равно `\BooleanFalse`.                        |
| `\IfNoValueTF{arg}{true}{false}` | Проверяет, равен ли `arg` маркеру `-NoValue-`.                                 |
| `\IfNoValueT{arg}{true}`    | Выполняет `true` код, если `arg` равен `-NoValue-`.                             |
| `\IfNoValueF{arg}{false}`   | Выполняет `false` код, если `arg` **не** равен `-NoValue-`.                     |
| `\IfValueTF{arg}{true}{false}` | Обратная логика: `true` если `arg` **имеет** значение.                         |
| `\IfValueT{arg}{true}`      | Выполняет `true` код, если `arg` **имеет** значение.                            |
| `\IfValueF{arg}{false}`     | Выполняет `false` код, если `arg` **не имеет** значения.                        |
| `\IfBlankTF{arg}{true}{false}` | Проверяет, является ли `arg` пустым или содержит только пробелы.               |
| `\IfBlankT{arg}{true}`      | Выполняет `true` код, если `arg` пустой/пробельный.                            |
| `\IfBlankF{arg}{false}`     | Выполняет `false` код, если `arg` **не** пустой.                               |

Пример использования:

\NewDocumentCommand\foo{o m}{
  \IfNoValueTF{#1}
    {Команда без опции: #2}
    {Команда с опцией [#1] и аргументом #2}
}

Таблица с описанием процессоров аргументов и примерами их использования:

| Процессор                     | Описание                                                                 | Пример использования                                                                 |
|--------------------------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| **`\SplitArgument{n}{sep}`**   | Разделяет аргумент по `sep` на `n+1` частей, оборачивая в `{}`.          | `\NewDocumentCommand\foo{>{\SplitArgument{2}{;}}m}{#1}` → `\foo{a;b;c}` → `{a}{b}{c}` |
| **`\SplitList{sep}`**          | Разделяет аргумент по `sep` на неограниченное число частей.              | `\NewDocumentCommand\foo{>{\SplitList{,}}m}{\ProcessList{#1}{\textbf}}` → `\foo{a,b}` → **a** **b** |
| **`\ProcessList{list}{cmd}`**  | Применяет `cmd` к каждому элементу `list` (используется с `\SplitList`). | `\ProcessList{{a}{b}}{\textbf}` → **a****b**                                         |
| **`\ReverseBoolean`**          | Инвертирует булевы значения (`\BooleanTrue` ↔ `\BooleanFalse`).          | `\NewDocumentCommand\foo{>{\ReverseBoolean}s}{Star: \IfBooleanT{#1}{YES}}` → `\foo*` выведет "Star: NO" |
| **`\TrimSpaces`**              | Удаляет пробелы в начале/конце аргумента.                                | `\NewDocumentCommand\foo{>{\TrimSpaces}m}{[#1]}` → `\foo{  text  }` → `[text]`       |
| **Комбинация процессоров**     | Процессоры применяются справа налево.                                    | `>{\TrimSpaces} >{\SplitList{,}} m` → сначала разделит запятыми, затем обрежет пробелы. |

Примеры использования

Разделение аргументов с обработкой:

\NewDocumentCommand\formatlist{>{\SplitList{,}}m}{
  \ProcessList{#1}{\textbf}
}
\formatlist{a, b, c} % → **a** **b** **c**

Обработка ключевых значений:

\NewDocumentCommand\setoptions{>{\TrimSpaces}m}{
  \keys_set:nn {my-module} {#1}
}
\setoptions{ key1 = value1 , key2 = value2 }

Инверсия логики звездочки:

\NewDocumentCommand\checkstar{>{\ReverseBoolean}s}{
  \IfBooleanT{#1}{Звезды НЕТ} \IfBooleanF{#1}{Звезда ЕСТЬ}
}
\checkstar* % Выведет "Звезда ЕСТЬ"

Многоэтапная обработка:

\NewDocumentCommand\process{>{\TrimSpaces} >{\SplitList{;}} m}{
  \ProcessList{#1}{\SomeCommand}
}
\process{ a; b; c } % → обработает как `{a}{b}{c}`