Синтаксис шаблонов TextFSM#

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

Шаблон TextFSM описывает, каким образом данные должны обрабатываться.

Любой шаблон состоит из двух частей:

  • определения переменных

  • эти переменные описывают, какие столбцы будут в табличном представлении

  • определения состояний

Пример разбора команды traceroute:

# Определение переменных:
Value ID (\d+)
Value Hop (\d+(\.\d+){3})

# Секция с определением состояний всегда должна начинаться с состояния Start
Start
#     Переменные      действие
   ^  ${ID} ${Hop} -> Record

Пример работы TextFSM (без звука)

Определение переменных#

В секции с переменными должны идти только определения переменных. Единственное исключение - в этом разделе могут быть комментарии.

В этом разделе не должно быть пустых строк. Для 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#

После действия может быть указано новое состояние:

  • состояние должно быть одним из зарезервированных или определенных в шаблоне

  • если входная строка совпала:

    • все действия выполняются,

    • считывается следующая строка,

    • затем текущее состояние меняется на новое, и обработка продолжается в новом состоянии.

Если в правиле используется действие Continue, то в нём нельзя использовать переход в другое состояние. Это правило нужно для того, чтобы в последовательности состояний не было петель.

Error Action#

Специальное действие Error останавливает всю обработку строк, отбрасывает все строки, которые были собраны до сих пор, и возвращает исключение.

Синтаксис этого действия такой:

^regex -> Error [word|"string"]