textfsm 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f381555ee4b666d74fb0fb9f8ed82d3881089872c9ce69d69bdb20e6febd1335
+  data.tar.gz: 9edc61cf09c9e24a494a0fb15aba98cc57162afba32bafa6dd8ccee5c00b414c
+SHA512:
+  metadata.gz: 7bb5d2d0907d9f1dee50c6db10cc3ad62681cbddb6d188a9053164502c37cbb3cb908d3538d3923f796ece79e311974fce95b63499595a69c5ab2a19901dea23
+  data.tar.gz: ba2cc24808ac78daad55cbd6bf7bb9c228b9f3965d865ad0801bca3c19c5d406873fc189a6627ea2187e1366c3367b69750c2957a2d728d4d2e62bcafd390c89

data/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

data/NOTICE

@@ -0,0 +1,15 @@
+TextFSM Ruby
+
+This project is a Ruby port of the parsing engine and CLI template selection
+from Google TextFSM (https://github.com/google/textfsm).
+
+Original TextFSM: Copyright 2010 Google Inc. All Rights Reserved.
+Original CLI tables: Copyright 2022 Google Inc. All Rights Reserved.
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Reference: TextFSM 2.1.0, commit f80bbb459c55ff5f21651e48d2529722d667af97.
+The Ruby source is a reimplementation, modified in 2026.
+Files in examples/ and test/fixtures/upstream/ are copied from that reference.
+test/fixtures/python_conformance.json contains results generated from the
+upstream parser tests and examples. The generator is in script/.
+

data/README.md

@@ -0,0 +1,289 @@
+# TextFSM Ruby
+
+使用 Ruby 实现的模板驱动文本解析状态机。读取 TextFSM 模板和半结构化文本，输出二维数组或 Hash 数组，适合解析网络设备 CLI 输出、系统命令输出等。
+
+解析语义参考 [Google TextFSM 2.1.0](https://github.com/google/textfsm/tree/f80bbb459c55ff5f21651e48d2529722d667af97)，运行时使用 Ruby 自身的正则引擎，不需要 Python 或外部进程；运行时依赖 Ruby 标准库 gem `json` 和 `strscan`。要求 Ruby 3.1 或以上。
+
+0.2 使用 `TextFSM` 模块组织 `Parser`、`Field`、`Rule`、`Table` 和 `CliTable`；公开方法与选项扩展接口按 Ruby 风格重新设计，不保留 0.1 的接口别名。
+
+## 安装
+
+本项目尚未发布到 RubyGems。在其他项目的 `Gemfile` 中使用本地路径：
+
+```ruby
+gem "textfsm", path: "/path/to/textfsm"
+```
+
+也可以构建并安装：
+
+```sh
+bundle install
+bundle exec rake build
+gem install ./pkg/textfsm-0.2.0.gem
+```
+
+源码仓库：[gatework/textfsm](https://github.com/gatework/textfsm)。
+
+## 快速使用
+
+```ruby
+require "textfsm"
+
+template = <<~'FSM'
+  Value Required INTERFACE (\S+)
+  Value ADDRESS (\S+)
+  Value STATUS (up|down|administratively down)
+  Value PROTOCOL (up|down)
+
+  Start
+    ^${INTERFACE}\s+${ADDRESS}\s+${STATUS}\s+${PROTOCOL}$$ -> Record
+FSM
+
+text = <<~TEXT
+  GigabitEthernet0/0 192.0.2.1 up up
+  GigabitEthernet0/1 unassigned administratively down down
+TEXT
+
+fsm = TextFSM::Parser.new(template)
+p fsm.header
+# => ["INTERFACE", "ADDRESS", "STATUS", "PROTOCOL"]
+p fsm.parse(text)
+# => [["GigabitEthernet0/0", "192.0.2.1", "up", "up"],
+#     ["GigabitEthernet0/1", "unassigned", "administratively down", "down"]]
+
+fsm.reset
+p fsm.parse_hashes(text)
+# => [{"INTERFACE"=>"GigabitEthernet0/0", "ADDRESS"=>"192.0.2.1",
+#      "STATUS"=>"up", "PROTOCOL"=>"up"}, ...]
+```
+
+模板使用单引号 heredoc（`<<~'FSM'`），避免 Ruby 提前处理正则中的反斜杠。`TextFSM::Parser.new` 的字符串参数是**模板内容**；从文件读取请用 `TextFSM::Parser.from_file("template.textfsm")`，也可以传入已打开的文件或 `StringIO`。IO 从当前位置读取并保持在读完的位置，不会自动 `rewind`。
+
+## 模板语法
+
+模板先声明连续的 `Value`，用空行分隔状态。初始状态必须叫 `Start`。状态之间用空行分隔；规则以一个空格、两个空格或一个制表符缩进，随后必须是 `^`。以 `#` 开始的注释行会被忽略。
+
+```text
+Value [选项,选项] NAME (正则表达式)
+
+Start
+  ^匹配规则 -> 行操作.记录操作 下一个状态
+```
+
+规则中的 `$NAME` 或 `${NAME}` 会替换为对应字段的捕获组。规则需要正则行尾锚点 `$` 时写 `$$`；需要匹配字面量美元符号时写 `\$$`。字段名和状态名最长 48 个字符。
+
+字段选项：
+
+| 选项 | 行为 |
+| --- | --- |
+| `Required` | 字段为空时丢弃当前记录 |
+| `Filldown` | 保存字段值，后续记录沿用，直到重新赋值或 `Clearall` |
+| `Fillup` | 新值向上填充此前连续的空字段，遇到非空值停止 |
+| `List` | 将多次匹配累积为数组 |
+| `Key` | 标记多模板表合并所使用的键 |
+
+选项按照声明顺序执行，保留 Python 的顺序语义，例如 `List,Required` 与 `Required,List` 在可选匹配或空值时可能有不同结果。
+
+行操作和记录操作可以省略；默认是 `Next.NoRecord`：
+
+| 操作 | 行为 |
+| --- | --- |
+| `Next` | 消耗当前行，从当前或目标状态的第一条规则处理下一行 |
+| `Continue` | 保留当前行，继续当前状态的下一条规则；不能同时指定目标状态 |
+| `Error ["消息"]` | 抛出 `TextFSM::ParseError`，包含模板规则行号和输入行 |
+| `NoRecord` | 保留当前字段，不输出记录 |
+| `Record` | 输出符合条件的记录，清除普通字段，保留 `Filldown` |
+| `Clear` | 清除普通字段，保留 `Filldown` |
+| `Clearall` | 清除全部字段，包括 `Filldown` 和列表缓存 |
+
+记录操作先于行操作执行。未匹配的行会被跳过，可添加 `^.* -> Error "Unexpected input"` 拒绝未识别的输入。缺失的普通字段输出 `""`，未匹配的列表输出 `[]`；纯未赋值的记录不会输出，实际匹配到的空字符串可以输出。
+
+输入结束时默认执行一次 `Record`。定义空的 `EOF` 状态可以关闭这一行为。跳转到 `End` 会停止解析并跳过最终记录；需要保留当前记录时使用 `Record End`。`EOF` 和 `End` 的显式状态定义必须为空。
+
+`Filldown` 本身也会让最终记录非空，因此可能产生尾部记录。通常给每条业务记录的标识字段设置 `Required`，或根据模板含义定义空 `EOF`。
+
+### 列表中的结构化数据
+
+`List` 字段包含 Python 风格的命名子捕获组时，每次匹配会产生一个 Hash：
+
+```text
+Value List PERSON ((?P<name>\w+)\s+(?P<age>\d+))
+
+Start
+  ^${PERSON}
+```
+
+解析 `Bob 32\nAlice 27\n` 后得到：
+
+```ruby
+[[[{ "name" => "Bob", "age" => "32" }, { "name" => "Alice", "age" => "27" }]]]
+```
+
+所有捕获值保持字符串；可选命名子组未匹配时为 `nil`。同一条规则里不能出现重复的命名捕获组，包括重复引用同一个 Value。
+
+## 分段解析与复用
+
+```ruby
+fsm = TextFSM::Parser.from_file("template.textfsm")
+fsm.parse(first_chunk, eof: false)
+rows = fsm.parse(last_chunk)
+
+fsm.reset
+rows = fsm.parse(another_command_output)
+```
+
+`parse` 和 `rows` 返回累计结果的深度冻结快照；它们不会自动重置解析器。需要可修改的数据时使用 `to_a`、`to_hashes` 或 `parse_hashes`，这些接口返回独立的深拷贝。分段必须按完整行切分，`eof: false` 仅抑制最终 `Record`，不缓存半行。`parse` 也接受可读取的 IO，但会一次读取内容。不同设备输出应先 `reset` 或使用新实例；有状态的实例不应由多个线程并发共享。`Fillup` 会更新解析器内部的历史行；此前返回的快照不变，后续 `parse`／`rows` 会包含回填后的结果。
+
+可用接口：`header`、`rows`、`current_state`、`states`、`state_names`、`fields_with_option("Key")`、`to_a`、`to_hashes`、`to_s`（重建去除注释的模板）。表头、状态规则及编译后的模式只读；字段的运行时状态保留在解析器内部。`fields_with_option` 也接受 `:Key` 等 Symbol。
+
+## 根据设备与命令选择模板
+
+`CliTable` 读取与 Python TextFSM 相同的 index 文件格式：
+
+```ruby
+require "textfsm/cli_table"
+
+table = TextFSM::CliTable.new(index: "index", template_dir: "/path/to/templates")
+table.parse(output, attributes: { "Vendor" => "Cisco", "Command" => "sh ver" })
+p table.header
+p table.to_a
+p table.to_hashes
+```
+
+index 示例：
+
+```text
+Template, Vendor, Command
+cisco_version_template, Cisco, sh[[ow]] ve[[rsion]]
+```
+
+按文件顺序选择第一条匹配记录；匹配从属性字符串开头开始，空单元格是通配条件，index 未定义的属性会被忽略。`Command` 中 `sh[[ow]]` 支持 `sh`、`sho`、`show`。index 遵循上游简单逗号分隔格式，不处理带引号的 CSV 字段。
+
+可绕过 index 显式传入模板：
+
+```ruby
+table = TextFSM::CliTable.new(template_dir: "/path/to/templates")
+table.parse(output, templates: "first.textfsm:second.textfsm")
+# templates 也接受文件名数组。
+```
+
+多个模板重复解析同一份输入，只合入新增列。有 `Key` 时按键匹配首条记录，否则按行位置合并。保留第一张表的行数，缺少匹配的新增列填 `""`。表格支持 Enumerable，行号从零开始。`IndexTable#match(attributes)` 返回首条匹配的只读 Hash，未命中返回 `nil`，无需换算行号。
+
+`Table#merge(other, keys: ["ID"])` 返回合入新列的新表，保留原表；`merge!` 更新当前表并返回自身。新表保留接收者的类型，因此 `CliTable#merge` 也保留索引、输入和键。表头和 `rows`／`table[index]` 只读；`to_a` 和 `to_hashes` 返回独立副本，嵌套的列表与 Hash 也不会共享可变数据。构造表格时拒绝重复列名和宽度不一致的行。
+
+`CliTable#keys` 返回模板声明的键，使用 `table.keys = ["ID"]` 显式设置，或 `table.keys += ["NAME"]` 增补。`key_for(row)` 返回键值数组，没有键时返回 `[]`。排序遵循 Ruby 自身的比较规则：
+
+```ruby
+table.sort!                                      # 按行比较
+table.sort_by! { |row| table.key_for(row) }        # 按声明的键排序
+table.sort_by! { |row| row[0].to_i }               # 明确按数值排序
+table.sort! { |left, right| right <=> left }       # 倒序
+```
+
+`load_index("another_index")` 可替换索引。多模板解析、合并或索引加载失败时保留上次成功的表头、数据、键及输入。
+
+## 命令行
+
+```sh
+# 本地源码运行；安装 gem 后可直接使用 textfsm 命令
+ruby exe/textfsm examples/cisco_version_template examples/cisco_version_example
+cat examples/cisco_version_example | ruby exe/textfsm examples/cisco_version_template
+ruby exe/textfsm --rows examples/cisco_version_template examples/cisco_version_example
+ruby exe/textfsm --format table examples/cisco_version_template examples/cisco_version_example
+ruby exe/textfsm --validate examples/cisco_version_template
+```
+
+默认输出 JSON 对象数组；`--rows` 输出包含 `header` 和 `rows` 的 JSON；`--format table` 输出制表符分隔的可读表格。成功退出码为 `0`，参数、文件、模板或解析错误为 `2`。`--validate` 只验证模板，不读取标准输入。
+
+## 扩展字段选项
+
+```ruby
+class Uppercase < TextFSM::Options::Base
+  def after_assign
+    field.value = field.value&.upcase
+  end
+end
+
+parser = TextFSM::Parser.new(template, options: { "Uppercase" => Uppercase })
+```
+
+模板中可以声明 `Value Uppercase NAME (...)`。显式传入的选项与五种内置选项合并，只对该解析器生效；内置注册表不可修改。选项类必须继承 `TextFSM::Options::Base`。
+
+可实现 `after_initialize`、`after_assign`、`after_clear`、`after_reset`、`before_record` 钩子，通过 `field.value` 读写当前值。在 `before_record` 中执行 `throw :skip_record` 可以丢弃当前记录；字段仍会按正常规则清除。选项的 `visible?` 返回 `false` 可以隐藏字段，输出列在模板加载时确定，`Fillup` 使用同一份列映射。隐藏字段仍执行选项钩子，可用于控制记录是否输出。
+
+## 工程约定
+
+- `lib/textfsm.rb` 是统一入口，各组件也可单独 `require "textfsm/parser"`、`require "textfsm/pattern"` 等。CLI 位于 `exe/textfsm`。
+- `exe/` 遵循 Bundler 的 gem 可执行文件约定，存放安装给使用者的命令；`script/` 存放项目维护脚本。`Gemfile.lock` 纳入 Git，固定开发和发布验证使用的依赖，不会打进 gem；使用者的依赖范围由 gemspec 声明。
+- 类和模块使用 `CamelCase`，方法、参数和实例变量使用 `snake_case`；查询使用 `?`，属性赋值使用 `=`。类方法写成 `def self.method_name`，解析状态属于实例，固定映射使用冻结常量。
+- 集合通过 `Enumerable`、`each`、`[]`、`size` 和 `empty?` 提供 Ruby 接口；需要代码块的迭代方法在未传块时返回 `Enumerator`。`merge`／`merge!` 区分创建新表和修改当前表，排序复用 Ruby 比较器。
+- 数据转换使用 `map`、`filter_map`、`transform_values`、`reduce` 等集合方法；简单转换使用单行 `{ ... }`，多行逻辑和有副作用的迭代使用 `do ... end`。简短取值使用条件表达式，复杂状态分支使用 `if`／`case`。
+- 构造方法组织对象初始化，声明解析等细节放入私有方法。字段选项通过明确的生命周期钩子扩展；错误使用 `TextFSM::Error` 的子类，预期的跳过记录使用 `catch`／`throw`。
+- 内部动作使用 Symbol，省略目标状态使用 `nil`；模板文本继续使用标准的 `Next`、`Record`、`Clearall` 等语法。
+- 正则编译使用 `StringScanner`，编译器的游标和分组栈不保留在最终 `Pattern` 对象中。模式始终从输入开头匹配。
+- `bundle exec rake` 执行 Minitest 和 RuboCop；`rake test`、`rake lint` 可分别运行。代码规则见 `.rubocop.yml`。
+- `bundle exec rake verify` 进一步构建 gem，在临时目录安装后逐文件核对源码内容，并验证独立加载与 CLI 输出、标准输入和退出码。生成的包位于 `pkg/`，不会发布到 RubyGems。
+
+## 发布到 RubyGems
+
+发布入口是 `script/release.rb`，也可通过 Rake 运行。直接执行脚本默认只检查和构建：
+
+```sh
+bundle install
+bundle exec rake release:check
+# 等价于 bundle exec ruby script/release.rb --dry-run
+```
+
+检查模式可以在尚未提交的工作区运行，不访问 RubyGems，也不会创建提交或标签。正式发布需要工作区干净，所有入包文件已提交到 Git：
+
+1. 修改 `lib/textfsm/version.rb` 中的版本号。新版本使用 RubyGems 版本格式，例如 `0.2.1` 或 `0.3.0.pre.1`。
+2. 运行 `bundle install` 更新 `Gemfile.lock`，再运行 `bundle exec rake release:check`。
+3. 提交并推送本次版本的源码与锁文件。
+4. 使用自己的 RubyGems 账号发布：
+
+```sh
+gem signin --host https://rubygems.org
+bundle exec rake release
+# 等价于 bundle exec ruby script/release.rb --push
+```
+
+凭据由 RubyGems 管理；自动化环境可通过密钥管理服务注入 `GEM_HOST_API_KEY`，密钥需有 `push_rubygem` 权限。需要 MFA 时由 `gem push` 处理交互。不要把密钥放进仓库或发布脚本。详见 [RubyGems 发布指南](https://guides.rubygems.org/publishing/)和 [API key scopes](https://guides.rubygems.org/api-key-scopes/)。
+
+正式发布复用 `rake verify` 的完整检查：执行测试、RuboCop 和构建，再将 gem 复制到独立临时目录，由 `script/verify_package.rb` 验证安装后的库、CLI 和文件内容。候选包在验证前后必须保持同一 SHA256，HEAD 和工作区也必须保持不变，随后上传该候选包到 `https://rubygems.org`，读取版本元数据核对 SHA256。输出包含源码提交号和包校验值；相同版本、相同校验值已发布时直接成功，相同版本内容不同时拒绝覆盖。构建使用提交时间作为 `SOURCE_DATE_EPOCH`，便于同一提交重复构建。
+
+上传后只重试查询，不自动重复上传。若提示结果未确认，先检查 RubyGems 上该版本及其校验值。脚本不创建或推送 Git 提交和标签；RubyGems 核对成功后，可按已发布版本标记源码，例如：
+
+```sh
+git tag -a v0.2.0 -m "Release v0.2.0"
+git push origin v0.2.0
+```
+
+## 兼容范围与验证
+
+本项目实现 TextFSM 模板解析、状态机、全部五种内置字段选项、列表命名子组、字典输出，以及命令索引与多模板表合并。官方示例保存在 `examples/`。
+
+Ruby 使用 Onigmo 正则引擎。本项目转换 Python 命名组 `(?P<name>...)`、命名与数字反向引用、贪婪／懒惰／占有量词、常用内联标志 `i/m/s/x/a/u`、Unicode 字符类及锚点语义。**这不是完整 Python `re` 引擎的替代实现**：Unicode 名称转义 `\N{...}`、条件组等不支持的扩展会报 `TemplateError`；两种引擎的大小写折叠、复杂后行断言等细节仍可能不同。使用额外模板库时，应以实际模板与输入执行对照测试。
+
+Ruby 的 `End` / `EOF` 跳转在后续调用中继续保持终止状态，重新解析需 `reset`；不会复现 Python 在后续调用中再次处理一行的边界行为。CLI JSON 格式和错误文案采用 Ruby 接口；未移植 Python `terminal` 的终端控制功能或 `texttable` 的完整展示/编辑 API。模板 IO 不自动回卷；结果采用快照语义；输入必须是字符串或可读取的 IO。
+
+运行测试：
+
+```sh
+bundle install
+bundle exec rake
+```
+
+测试包含单元测试及离线 Python 对照数据，正常运行无需 Python 或网络。`test/fixtures/python_conformance.json` 来自固定上游提交的 33 项原测试、8 个官方示例，以及 140 组确定性的选项/状态组合场景，共 203 组实例轨迹。对照校验表头、模板重建、选项元数据、累计结果、重置和目标状态。CI 覆盖 Ruby 3.1、3.2、3.3、3.4 和 4.0，每个版本执行 `rake verify`。额外回归覆盖结果隔离、自定义选项、隐藏列回填、索引事务、CLI 错误和正则语法边界。
+
+需要重新生成对照数据时：
+
+```sh
+git clone https://github.com/google/textfsm.git /tmp/google-textfsm
+git -C /tmp/google-textfsm checkout f80bbb459c55ff5f21651e48d2529722d667af97
+python3 script/generate_conformance.py /tmp/google-textfsm
+bundle exec rake
+```
+
+## 许可证
+
+Apache-2.0。原项目归属、参考版本及复制文件说明见 [NOTICE](NOTICE)，许可证全文见 [LICENSE](LICENSE)。

data/examples/cisco_bgp_summary_example

@@ -0,0 +1,15 @@
+BGP router identifier 192.0.2.70, local AS number 65550
+BGP table version is 9, main routing table version 9
+4 network entries using 468 bytes of memory
+4 path entries using 208 bytes of memory
+3/2 BGP path/bestpath attribute entries using 420 bytes of memory
+1 BGP AS-PATH entries using 24 bytes of memory
+1 BGP community entries using 24 bytes of memory
+0 BGP route-map cache entries using 0 bytes of memory
+0 BGP filter-list cache entries using 0 bytes of memory
+BGP using 1144 total bytes of memory
+BGP activity 12/4 prefixes, 12/4 paths, scan interval 5 secs
+
+Neighbor        V    AS MsgRcvd MsgSent   TblVer  InQ OutQ Up/Down  State/PfxRcd
+192.0.2.77      4 65551    6965    1766        9    0    0  5w4d           1
+192.0.2.78      4 65552    6965    1766        9    0    0  5w4d          10

data/examples/cisco_bgp_summary_template

@@ -0,0 +1,16 @@
+# Carry down the local end information so that it is present on each row item.
+Value Filldown RouterID (\S+)
+Value Filldown LocalAS (\d+)
+Value RemoteAS (\d+)
+Value Required RemoteIP (\d+(\.\d+){3})
+Value Uptime (\d+\S+)
+Value Received_V4 (\d+)
+Value Status (\D.*)
+
+Start
+  ^BGP router identifier ${RouterID}, local AS number ${LocalAS}
+  ^${RemoteIP}\s+\d+\s+${RemoteAS}(\s+\S+){5}\s+${Uptime}\s+${Received_V4} -> Record
+  ^${RemoteIP}\s+\d+\s+${RemoteAS}(\s+\S+){5}\s+${Uptime}\s+${Status} -> Record
+
+# Last record is already recorded then skip doing so here.
+EOF

data/examples/cisco_ipv6_interface_example

@@ -0,0 +1,53 @@
+Dialer0 is up, line protocol is up
+  IPv6 is enabled, link-local address is FE80::21B:2BFF:FECE:4EE3 
+  No Virtual link-local address(es):
+  Description: PPP Dialer
+  Stateless address autoconfig enabled
+  General-prefix in use for addressing
+  Global unicast address(es):
+    2001:4567:1212:B2:21B:2BFF:FECE:4EE3, subnet is 2001:4567:1212:B2::/64 [EUI/CAL/PRE]
+      valid lifetime 5041 preferred lifetime 5041
+    2001:4567:1111:56FF::1, subnet is 2001:4567:1111:56FF::1/128 [CAL/PRE]
+      valid lifetime 5945 preferred lifetime 2344
+  Joined group address(es):
+    FF02::1
+    FF02::2
+    FF02::1:FF00:1
+    FF02::1:FFCE:4EE3
+  MTU is 1500 bytes
+  ICMP error messages limited to one every 100 milliseconds
+  ICMP redirects are enabled
+  ICMP unreachables are sent
+  Input features: Access List
+  Inbound access list IPV6-IN
+  ND DAD is enabled, number of DAD attempts: 1
+  ND reachable time is 30000 milliseconds (using 21397)
+  Hosts use stateless autoconfig for addresses.
+Vlan1 is up, line protocol is up
+  IPv6 is enabled, link-local address is FE80::21B:2BFF:FECE:4EE3 
+  No Virtual link-local address(es):
+  Description: Local VLAN
+  General-prefix in use for addressing
+  Global unicast address(es):
+    2001:4567:1212:5600::1, subnet is 2001:4567:1212:5600::/64 [CAL/PRE]
+      valid lifetime 5943 preferred lifetime 2342
+  Joined group address(es):
+    FF02::1
+    FF02::2
+    FF02::1:2
+    FF02::1:FF00:1
+    FF02::1:FFCE:4EE3
+    FF05::1:3
+  MTU is 1500 bytes
+  ICMP error messages limited to one every 100 milliseconds
+  ICMP redirects are enabled
+  ICMP unreachables are sent
+  ND DAD is enabled, number of DAD attempts: 1
+  ND reachable time is 30000 milliseconds (using 26371)
+  ND advertised reachable time is 0 (unspecified)
+  ND advertised retransmit interval is 0 (unspecified)
+  ND router advertisements are sent every 200 seconds
+  ND router advertisements live for 1800 seconds
+  ND advertised default router preference is Medium
+  Hosts use stateless autoconfig for addresses.
+  Hosts use DHCP to obtain other configuration.

data/examples/cisco_ipv6_interface_template

@@ -0,0 +1,27 @@
+Value Interface (\S+)
+Value Admin (\S+)
+Value Oper (\S+)
+Value Description (.*)
+Value LinkLocal (\S+)
+Value List Addresses (\S+)
+Value List Subnets (\S+)
+Value List GroupAddresses (\S+)
+Value Mtu (\d+)
+
+Start
+  ^${Interface} is ${Admin}, line protocol is ${Oper}
+  ^.*link-local address is ${LinkLocal}
+  ^  Description: ${Description}
+  ^  Global unicast address -> Unicast
+  ^  Joined group address -> Multicast
+  ^  MTU is ${Mtu} bytes -> Record
+
+Unicast
+  ^    ${Addresses}, subnet is ${Subnets}
+  ^  Joined group address -> Multicast
+  ^  \S -> Start
+
+Multicast
+  ^    ${GroupAddresses}
+  ^  MTU is ${Mtu} bytes -> Record
+  ^  \S -> Start