textfsm 0.2.0

data/lib/textfsm/options.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Ruby port of Google TextFSM options. Copyright 2010 Google Inc.
+# Modified in 2026. Licensed under Apache-2.0; see LICENSE.
+module TextFSM
+  module Options
+    class Base
+      attr_reader :field
+
+      def initialize(field)
+        @field = field
+      end
+
+      def after_initialize
+      end
+
+      def after_assign
+      end
+
+      def after_clear
+      end
+
+      def after_reset
+      end
+
+      def before_record
+      end
+
+      def visible?
+        true
+      end
+    end
+
+    class Required < Base
+      def before_record
+        throw :skip_record if field.empty?
+      end
+    end
+
+    class Filldown < Base
+      def after_assign
+        @saved_value = field.value
+      end
+
+      def after_clear
+        field.value = @saved_value
+      end
+
+      def after_reset
+        @saved_value = nil
+      end
+    end
+
+    class Fillup < Base
+      def after_assign
+        field.parser.fill_up(field) unless field.empty?
+      end
+    end
+
+    class Key < Base; end
+
+    class List < Base
+      def after_initialize
+        @items = []
+      end
+
+      def after_assign
+        match = field.pattern.match(field.value) if field.value && !field.pattern.names.empty?
+        @items << (match ? field.pattern.named_captures(match) : field.value)
+      end
+
+      def after_clear
+        @items = [] unless field.option?("Filldown")
+      end
+
+      def after_reset
+        @items = []
+      end
+
+      def before_record
+        field.value = @items.dup
+      end
+    end
+
+    BUILTINS = {
+      "Required" => Required,
+      "Filldown" => Filldown,
+      "Fillup" => Fillup,
+      "List" => List,
+      "Key" => Key
+    }.freeze
+  end
+end

data/lib/textfsm/parser.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+# Ruby port of Google TextFSM parser. Copyright 2010 Google Inc.
+# Modified in 2026. Licensed under Apache-2.0; see LICENSE.
+require_relative "field"
+require_relative "rule"
+require_relative "data"
+
+module TextFSM
+  class Parser
+    LINE_SEPARATOR = /\r\n|[\n\r\v\f\x1c-\x1e\u0085\u2028\u2029]/
+    private_constant :LINE_SEPARATOR
+
+    attr_reader :header, :states, :current_state
+
+    def initialize(template, options: {})
+      @states = {}
+      @fields = {}
+      @option_types = Options::BUILTINS.merge(options.transform_keys(&:to_s)).freeze
+      @option_types.each_value do |type|
+        raise ArgumentError, "options must inherit from TextFSM::Options::Base" unless type.is_a?(Class) && type < Options::Base
+      end
+      parse_template(read_template(template))
+      @fields.freeze
+      @states.each_value(&:freeze)
+      @states.freeze
+      @output_fields = @fields.each_value.select(&:visible?).freeze
+      @header = @output_fields.map(&:name).freeze
+      reset
+    end
+
+    def self.from_file(path, **options)
+      new(File.read(path, encoding: "UTF-8"), **options)
+    end
+
+    def state_names
+      @states.keys
+    end
+
+    def rows
+      Data.copy(@rows, immutable: true)
+    end
+
+    def to_a
+      Data.copy(@rows)
+    end
+
+    def to_hashes
+      to_a.map { |row| @header.zip(row).to_h }
+    end
+
+    def reset
+      @current_state = "Start"
+      @rows = []
+      @fields.each_value(&:reset)
+      self
+    end
+
+    # Calls accumulate state until reset. Chunks must end on a line boundary;
+    # eof: false defers the implicit final Record. Results are frozen snapshots.
+    def parse(text, eof: true)
+      consume_input(text, eof: eof)
+      rows
+    end
+
+    def parse_hashes(text, eof: true)
+      consume_input(text, eof: eof)
+      to_hashes
+    end
+
+    def fields_with_option(name)
+      name = name.to_s
+      raise ArgumentError, "Unknown option #{name.inspect}" unless @option_types.key?(name)
+
+      @fields.each_value.filter_map { |field| field.name if field.option?(name) }
+    end
+
+    # Option callbacks use the same visible-column mapping as record output.
+    def fill_up(field)
+      column = @output_fields.index(field)
+      return unless column
+
+      @rows.reverse_each do |row|
+        value = row[column]
+        break if value && !(value.respond_to?(:empty?) && value.empty?)
+
+        row[column] = Data.copy(field.value)
+      end
+    end
+
+    def to_s
+      output = "#{@fields.values.join("\n")}\n"
+      @states.each do |state, rules|
+        output << "\n#{state}\n"
+        rules.each do |rule|
+          output << "#{rule}\n"
+        end
+      end
+      output
+    end
+
+    private
+
+    def terminal?
+      @current_state == "End" || @current_state == "EOF"
+    end
+
+    def consume_input(text, eof:)
+      return if terminal?
+
+      text = text.read if text.respond_to?(:read)
+      raise ArgumentError, "text must be a String or readable IO" unless text.is_a?(String)
+
+      # StringScanner advances by bytes, including for multibyte input, without
+      # allocating all lines or repeatedly finding character offsets.
+      scanner = StringScanner.new(text)
+      while (line = scanner.scan_until(LINE_SEPARATOR))
+        process_line(line.byteslice(0, line.bytesize - scanner.matched_size))
+        break if terminal?
+      end
+      process_line(scanner.rest) unless terminal? || scanner.eos?
+      append_record if eof && @current_state != "End" && !@states.key?("EOF")
+    end
+
+    def read_template(template)
+      template = template.read if template.respond_to?(:read)
+      raise TemplateError, "Template must be a String or readable IO" unless template.is_a?(String)
+
+      template
+    end
+
+    def parse_template(template)
+      reading_fields = true
+      state = nil
+      template.each_line.with_index(1) do |raw, line_number|
+        line = raw.rstrip
+        next if line.lstrip.start_with?("#")
+
+        if line.empty?
+          reading_fields = false
+          state = nil
+        elsif reading_fields
+          parse_field(line, line_number)
+        elsif state.nil?
+          state = parse_state(line, line_number)
+        else
+          raise TemplateError, "Missing whitespace or '^' before rule. Line: #{line_number}." unless line.start_with?(" ^", "  ^", "\t^")
+
+          @states.fetch(state) << Rule.new(line, line_number: line_number, fields: @fields)
+        end
+      end
+      validate_states
+    end
+
+    def parse_field(line, line_number)
+      unless line.start_with?("Value ")
+        message = @fields.empty? ? "No Value definitions found" : "Expected blank line after last Value entry"
+        raise TemplateError, message
+      end
+      field = Field.new(line, parser: self, options: @option_types)
+      raise TemplateError, "Duplicate Value #{field.name.inspect}" if @fields.key?(field.name)
+
+      @fields[field.name] = field
+    rescue TemplateError => e
+      raise TemplateError, "#{e.message}. Line: #{line_number}."
+    end
+
+    def parse_state(line, line_number)
+      if !line.match?(/\A[\p{L}\p{N}_]+\z/) || line.length > 48 || Rule::OPERATIONS.include?(line)
+        raise TemplateError, "Invalid state name #{line.inspect}. Line: #{line_number}."
+      end
+      raise TemplateError, "Duplicate state #{line.inspect}. Line: #{line_number}." if @states.key?(line)
+
+      @states[line.freeze] = []
+      line
+    end
+
+    def validate_states
+      raise TemplateError, "Missing state 'Start'." unless @states.key?("Start")
+
+      %w[End EOF].each do |state|
+        raise TemplateError, "Non-empty '#{state}' state." if @states.key?(state) && !@states[state].empty?
+      end
+      @states.delete("End")
+      @states.each do |state, rules|
+        rules.each do |rule|
+          next if rule.line_action == :error || rule.next_state.nil? || %w[End EOF].include?(rule.next_state)
+          next if @states.key?(rule.next_state)
+
+          raise TemplateError, "State #{rule.next_state.inspect} not found, referenced in #{state.inspect}. Line: #{rule.line_number}."
+        end
+      end
+    end
+
+    def process_line(line)
+      @states.fetch(@current_state).each do |rule|
+        match = rule.pattern.match(line)
+        next unless match
+
+        rule.pattern.named_captures(match).each do |name, value|
+          @fields[name]&.assign(value)
+        end
+        case rule.record_action
+        when :record
+          append_record
+        when :clear
+          @fields.each_value(&:clear)
+        when :clear_all
+          @fields.each_value(&:reset)
+        end
+        if rule.line_action == :error
+          message = rule.error_message ? "Error: #{rule.error_message}" : "State Error raised"
+          raise ParseError, "#{message}. Rule Line: #{rule.line_number}. Input Line: #{line}."
+        end
+        next if rule.line_action == :continue
+
+        @current_state = rule.next_state if rule.next_state
+        break
+      end
+    end
+
+    def append_record
+      catch(:skip_record) do
+        @fields.each_value(&:prepare_record)
+        record = @output_fields.map(&:value)
+        unless record.all? { |value| value.nil? || value == [] }
+          @rows << Data.copy(record.map { |value| value.nil? ? "" : value })
+        end
+      end
+      @fields.each_value(&:clear)
+    end
+  end
+end

data/lib/textfsm/pattern.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require "strscan"
+require_relative "errors"
+
+module TextFSM
+  # Compile Python-style template patterns into immutable Ruby matchers.
+  class Pattern
+    attr_reader :source, :regexp, :names
+
+    def initialize(source)
+      raise ArgumentError, "pattern must be a String" unless source.is_a?(String)
+
+      @source = source.dup.freeze
+      expression, @group_names = Compiler.new(@source).compile
+      @regexp = Regexp.new("\\A(?:#{expression})").freeze
+      @names = @group_names.keys.freeze
+      freeze
+    rescue RegexpError, ArgumentError, RangeError => e
+      raise TemplateError, "Invalid regular expression #{source.inspect}: #{e.message}"
+    end
+
+    def match(text)
+      @regexp.match(text)
+    end
+
+    def match?(text)
+      @regexp.match?(text)
+    end
+
+    def named_captures(match)
+      @group_names.transform_values { |internal_name| match[internal_name] }
+    end
+
+    # Ruby drops unnamed captures when named captures are present. Giving every
+    # capture an internal name preserves Python's numeric backreferences.
+    class Compiler
+      ASSERTIONS = %w[A Z z b B].freeze
+      CHARACTER_CLASSES = { "d" => "\\p{Nd}", "w" => "\\p{L}\\p{N}_", "s" => "\\p{Space}\\x1c-\\x1f" }.freeze
+      FLAG_NAMES = { "m" => :multiline, "s" => :dotall, "x" => :extended, "a" => :ascii }.freeze
+
+      def initialize(source)
+        @scanner = StringScanner.new(source)
+        @output = []
+        @group_names = {}
+        @captures = []
+        @groups = []
+        @flags = { multiline: false, dotall: false, extended: false, ascii: false }
+        @has_expression = false
+        @atom_start = nil
+        @repeatable = false
+        @quantified = false
+      end
+
+      def compile
+        until @scanner.eos?
+          character = @scanner.getch
+          next if @flags[:extended] && character.match?(/[ \t\n\r\f\v]/)
+
+          compile_token(character)
+        end
+        raise ArgumentError, "unbalanced parenthesis" unless @groups.empty?
+
+        [@output.join, @group_names.freeze]
+      end
+
+      private
+
+      def compile_token(character)
+        case character
+        when "\\"
+          assertion = ASSERTIONS.include?(@scanner.peek(1))
+          emit_atom(escape(in_class: false), repeatable: !assertion)
+        when "[" then emit_atom(character_class)
+        when "(" then open_group
+        when ")" then close_group
+        when "^", "$" then emit_atom(anchor(character), repeatable: false)
+        when "." then emit_atom(@flags[:dotall] ? "(?m:.)" : ".")
+        when "|"
+          @output << character
+          @atom_start = nil
+          @has_expression = true
+        when "*", "+", "?" then quantifier(character)
+        when "{"
+          count = @scanner.scan(/(?:\d+(?:,\d*)?|,\d*)\}/)
+          count ? quantifier("{#{count}") : emit_atom("\\{")
+        when "#"
+          @flags[:extended] ? @scanner.skip(/[^\n]*/) : emit_atom("\\#")
+        else emit_atom(Regexp.escape(character))
+        end
+      end
+
+      def emit_atom(expression, repeatable: true)
+        @atom_start = @output.length
+        @repeatable = repeatable
+        @quantified = false
+        @has_expression = true
+        @output << expression
+      end
+
+      def anchor(character)
+        return character if @flags[:multiline]
+
+        character == "^" ? "\\A" : "\\Z"
+      end
+
+      def quantifier(expression)
+        raise ArgumentError, "nothing to repeat" unless @atom_start && @repeatable
+        raise ArgumentError, "multiple repeat" if @quantified
+
+        expression = counted_quantifier(expression) if expression.start_with?("{")
+        modifier = @scanner.scan(/[?+]/)
+        if modifier == "+"
+          atom = @output.slice!(@atom_start..).join
+          @output << "(?>#{atom}#{expression})"
+        else
+          @output << expression
+          @output << modifier if modifier
+        end
+        @quantified = true
+      end
+
+      def counted_quantifier(expression)
+        minimum, maximum = expression[1...-1].split(",", -1)
+        minimum = minimum.empty? ? 0 : Integer(minimum, 10)
+        maximum = if maximum.nil?
+                    minimum
+                  elsif !maximum.empty?
+                    Integer(maximum, 10)
+                  end
+        raise ArgumentError, "minimum repeat exceeds maximum" if maximum && minimum > maximum
+
+        # Ruby treats {n}? as an optional n-character block. An explicit range
+        # retains Python's required count when the lazy suffix is appended.
+        "{#{minimum},#{maximum}}"
+      end
+
+      def escape(in_class:)
+        character = @scanner.getch
+        raise ArgumentError, "trailing backslash" unless character
+
+        return octal(character + @scanner.scan(/[0-7]{0,2}/)) if character == "0" || (in_class && character.match?(/[0-7]/))
+        raise ArgumentError, "invalid character class escape \\#{character}" if in_class && %w[A B Z z 8 9].include?(character)
+        return numeric_reference(character) if !in_class && character.match?(/[1-9]/)
+        return "\\z" if !in_class && %w[Z z].include?(character)
+        return word_boundary(character) if !in_class && %w[b B].include?(character)
+        return unicode_escape(character) if %w[x u U].include?(character)
+
+        character_class_escape(character, in_class: in_class) || literal_escape(character)
+      end
+
+      def character_class_escape(character, in_class:)
+        return if @flags[:ascii]
+
+        if (body = CHARACTER_CLASSES[character.downcase])
+          return body if in_class && character == character.downcase
+
+          "[#{'^' if character == character.upcase}#{body}]"
+        end
+      end
+
+      def literal_escape(character)
+        raise ArgumentError, "\\N is not supported; use literal Unicode characters" if character == "N"
+        if character.match?(/[A-Za-z]/) && !"AbBdDsSwWZzfnrtvuxUa".include?(character)
+          raise ArgumentError, "unsupported escape \\#{character}"
+        end
+
+        "\\#{character}"
+      end
+
+      def numeric_reference(character)
+        digits = character + @scanner.scan(/[0-9]?/)
+        if digits.match?(/\A[0-7]{2}\z/) && (last_digit = @scanner.scan(/[0-7]/))
+          return octal(digits + last_digit)
+        end
+
+        internal_name = @captures[digits.to_i - 1]
+        raise ArgumentError, "invalid group reference #{digits}" unless internal_name
+
+        backreference(internal_name)
+      end
+
+      def backreference(internal_name)
+        raise ArgumentError, "cannot refer to an open group" if @groups.any? { |group| group[:capture] == internal_name }
+
+        "\\k<#{internal_name}>"
+      end
+
+      def word_boundary(character)
+        word = @flags[:ascii] ? "[a-zA-Z0-9_]" : "[\\p{L}\\p{N}_]"
+        boundary = "(?:(?<!#{word})(?=#{word})|(?<=#{word})(?!#{word}))"
+        character == "b" ? boundary : "(?!#{boundary})"
+      end
+
+      def unicode_escape(character)
+        length = { "x" => 2, "u" => 4, "U" => 8 }.fetch(character)
+        digits = @scanner.scan(/[0-9a-fA-F]{#{length}}/)
+        raise ArgumentError, "incomplete Unicode or hexadecimal escape" unless digits
+
+        Regexp.escape(digits.to_i(16).chr(Encoding::UTF_8))
+      end
+
+      def octal(digits)
+        codepoint = digits.to_i(8)
+        raise ArgumentError, "octal escape outside range 0-0o377" if codepoint > 255
+
+        Regexp.escape(codepoint.chr(Encoding::UTF_8))
+      end
+
+      def character_class
+        expression = +"["
+        expression << @scanner.getch if @scanner.peek(1) == "^"
+        expression << "\\]" if @scanner.scan(/\]/)
+        until @scanner.eos?
+          character = @scanner.getch
+          return "#{expression}]" if character == "]"
+
+          expression << case character
+                        when "\\" then escape(in_class: true)
+                        when "[" then "\\["
+                        when "&" then "\\&"
+                        else character
+                        end
+        end
+        raise ArgumentError, "unterminated character class"
+      end
+
+      def open_group
+        return capture unless @scanner.scan(/\?/)
+
+        if @scanner.scan(/P<([^>]+)>/)
+          name = @scanner[1]
+          unless name.match?(/\A[\p{L}_][\p{L}\p{N}_]*\z/) && !@group_names.key?(name)
+            raise ArgumentError, "invalid or duplicate group name #{name.inspect}"
+          end
+
+          return capture(name.freeze)
+        end
+        if @scanner.scan(/P=([^)]*)\)/)
+          name = @scanner[1]
+          internal_name = @group_names[name]
+          raise ArgumentError, "unknown group name #{name.inspect}" unless internal_name
+
+          return emit_atom(backreference(internal_name))
+        end
+        return if @scanner.skip(/#(?:\\.|[^)])*\)/)
+        return inline_flags if @scanner.scan(/([aimsux]*)(?:-([imsx]+))?([:)])/)
+        if (extension = @scanner.scan(/<=|<!|=|!|>/))
+          return push_group("(?#{extension}")
+        end
+
+        raise ArgumentError, "unsupported group extension at byte offset #{@scanner.pos - 2}"
+      end
+
+      def capture(name = nil)
+        internal_name = "tfsm_capture_#{@captures.length + 1}".freeze
+        @captures << internal_name
+        @group_names[name] = internal_name if name
+        push_group("(?<#{internal_name}>", capture: internal_name)
+      end
+
+      def push_group(expression, capture: nil)
+        @groups << { flags: @flags.dup, start: @output.length, capture: capture }
+        @output << expression
+        @atom_start = nil
+        @has_expression = true
+      end
+
+      def close_group
+        group = @groups.pop
+        raise ArgumentError, "unbalanced parenthesis" unless group
+
+        @flags = group[:flags]
+        @output << ")"
+        @atom_start = group[:start]
+        @repeatable = true
+        @quantified = false
+      end
+
+      def inline_flags
+        enabled = @scanner[1]
+        disabled = @scanner[2]
+        ending = @scanner[3]
+        validate_flags(enabled, disabled, ending)
+
+        ruby_on = enabled.delete("amsu")
+        ruby_off = disabled.to_s.delete("ms")
+        flags = ruby_on + (ruby_off.empty? ? "" : "-#{ruby_off}")
+        if ending == ":"
+          push_group("(?#{flags}:")
+        elsif !flags.empty?
+          @output << "(?#{flags})"
+        end
+        enabled.each_char do |flag|
+          @flags[FLAG_NAMES[flag]] = true if FLAG_NAMES.key?(flag)
+        end
+        disabled.to_s.each_char do |flag|
+          @flags[FLAG_NAMES[flag]] = false if FLAG_NAMES.key?(flag)
+        end
+        @flags[:ascii] = false if enabled.include?("u")
+      end
+
+      def validate_flags(enabled, disabled, ending)
+        if (enabled.include?("a") && enabled.include?("u")) || enabled.each_char.any? { |flag| disabled.to_s.include?(flag) }
+          raise ArgumentError, "incompatible inline flags"
+        end
+        return unless ending == ")"
+
+        raise ArgumentError, "global flags must occur at the start of the expression" if @has_expression || enabled.empty? || disabled
+
+        character_mode = enabled[/[au]/]
+        return unless character_mode
+
+        raise ArgumentError, "incompatible global character flags" if @global_character_mode && @global_character_mode != character_mode
+
+        @global_character_mode = character_mode
+      end
+    end
+
+    private_constant :Compiler
+  end
+end