Синтаксис шаблонов TextFSM
В этом разделе описан синтаксис шаблонов на основе документации TextFSM. В следующем разделе показаны примеры использования синтаксиса. Поэтому, в принципе, можно перейти сразу к следующему разделу, а к этому возвращаться по необходимости, для тех ситуаций, для которых нет примера, и когда нужно перечитать, что означает какой-то параметр.
Шаблон TextFSM описывает, каким образом данные должны обрабатываться.
Любой шаблон состоит из двух частей:
- определения переменных
- эти переменные описывают, какие столбцы будут в табличном представлении
- определения состояний
Пример разбора команды traceroute:
# Определение переменных: Value ID (\d+) Value Hop (\d+(\.\d+){3}) # Секция с определением состояний всегда должна начинаться с состояния Start Start # Переменные действие ^ ${ID} ${Hop} -> Record
Определение переменных
В секции с переменными должны идти только определения переменных. Единственное исключение - в этом разделе могут быть комментарии.
В этом разделе не должно быть пустых строк. Для TextFSM пустая строка означает завершение секции определения переменных.
Формат описания переменных:
Value [option[,option...]] name regex
Синтаксис описания переменных (для каждой опции ниже мы рассмотрим примеры):
Value
- это ключевое слово, которое указывает, что создается переменная. Его обязательно нужно указывать - option - опции, которые определяют, как работать с переменной. Если нужно указать несколько опций, они должны быть отделены запятой, без пробелов. Поддерживаются такие опции:
- Filldown - значение, которое ранее совпало с регулярным выражением, запоминается до следующей обработки строки (если не было явно очищено или снова совпало регулярное выражение).
- это значит, что последнее значение столбца, которое совпало с регулярным выражением, запоминается и используется в следующих строках, если в них не присутствовал этот столбец.
- Key - определяет, что это поле содержит уникальный идентификатор строки
- Required - строка, которая обрабатывается, будет записана только в том случае, если эта переменная присутствует.
- List - значение - это список, и каждое совпадение с регулярным выражением будет добавлять в список элемент. По умолчанию каждое следующее совпадение перезаписывает предыдущее.
- Fillup - работает как Filldown, но заполняет пустые значение выше до тех пор, пока не найдет совпадение. Не совместимо с Required.
name
- имя переменной, которое будет использоваться как имя колонки. Зарезервированные имена не должны использоваться как имя переменной. regex
- регулярное выражение, которое описывает переменную. Регулярное выражение должно быть в скобках.
Определение состояний
После определения переменных нужно описать состояния:
- каждое определение состояния должно быть отделено пустой строкой (как минимум, одной)
- первая строка - имя состояния
- затем идут строки, которые описывают правила
- правила должны начинаться с пробела и символа
^
Начальное состояние всегда Start. Входные данные сравниваются с текущим состоянием, но в строке правила может быть указано, что нужно перейти к другому состоянию.
Проверка выполняется построчно, пока не будет достигнут EOF(конец файла), или текущее состояние перейдет в состояние End.
Зарезервированные состояния
Зарезервированы такие состояния:
- Start - это состояние обязательно должно быть указано. Без него шаблон не будет работать.
- End - это состояние завершает обработку входящих строк и не выполняет состояние EOF.
- EOF - это неявное состояние, которое выполняется всегда, когда обработка дошла до конца файла. Выглядит оно таким образом:
EOF ^.* -> Record
EOF записывает текущую строку, прежде чем обработка завершается. Если это поведение нужно изменить, надо явно в конце шаблона написать EOF:
EOF
Правила состояний
Каждое состояние состоит из одного или более правил:
- TextFSM обрабатывает входящие строки и сравнивает их с правилами
- если правило (регулярное выражение) совпадает со строкой, выполняются действия, которые описаны в правиле, и для следующей строки процесс повторяется заново, с начала состояния.
Правила должны быть описаны в таком формате:
^regex [-> action]
В правиле:
- каждое правило должно начинаться с пробела и символа
^
- символ
^
означает начало строки и всегда должен указываться явно
- regex - это регулярное выражение, в котором могут использоваться переменные
- для указания переменной,\ может использоваться синтаксис
$ValueName
или ${ValueName}
(этот формат предпочтителен) - в правиле на место переменных подставляются регулярные выражения, которые они описывают
- если нужно явно указать символ конца строки, используется значение
$$
Действия в правилах
После регулярного выражения в правиле могут указываться действия:
- между регулярным выражением и действием должен быть символ
->
- действия могут состоять из трех частей в таком формате: L.R S
- L - Line Action - действия, которые применяются к входящей строке
- R - Record Action - действия, которые применяются к собранным значениям
- S - State Transition - переход в другое состояние
- по умолчанию используется Next.NoRecord
Line Actions
Line Actions:
- Next - обработать строку, прочитать следующую и начать проверять её с начала состояния. Это действие используется по умолчанию, если не указано другое
- Continue - продолжить обработку правил, как будто совпадения не было, при этом значения присваиваются
Record Action
Record Action - опциональное действие, которое может быть указано после Line Action. Они должны быть разделены точкой. Типы действий:
- NoRecord - не выполнять ничего. Это действие по умолчанию, когда другое не указано
- Record - запомнить значения, которые совпали с правилом. Все переменные, кроме тех, где указана опция Filldown, обнуляются.
- Clear - обнулить все переменные, кроме тех, где указана опция Filldown.
- Clearall - обнулить все переменные.
Разделять действия точкой нужно только в том случае, если нужно указать и Line, и Record действия. Если нужно указать только одно из них, точку ставить не нужно.
State Transition
После действия может быть указано новое состояние:
- состояние должно быть одним из зарезервированных или определенных в шаблоне
- если входная строка совпала:
- все действия выполняются,
- считывается следующая строка,
- затем текущее состояние меняется на новое, и обработка продолжается в новом состоянии.
Если в правиле используется действие , то в нём нельзя использовать переход в другое состояние. Это правило нужно для того, чтобы в последовательности состояний не было петель.
Error Action
Специальное действие Error останавливает всю обработку строк, отбрасывает все строки, которые были собраны до сих пор, и возвращает исключение.
Синтаксис этого действия такой:
^regex -> Error [word|"string"]