expect-pty 0.5.3 → 0.6.1

data/Rakefile

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-require "rake/testtask"
-
-Rake::TestTask.new do |task|
-  task.libs << "test"
-  task.pattern = "test/**/*_test.rb"
-  task.warning = true
-end
-
-desc "Check Ruby style and common mistakes"
-task :lint do
-  ruby "-S", "rubocop"
-end
-
-task default: %i[lint test]
-
-namespace :test do
-  desc "Log in over SSH and verify multiple scripts and persisted logs (opt-in)"
-  task :ssh do
-    ruby "test/integration/ssh_scripts.rb"
-  end
-
-  desc "Log in over SSH and verify real PTY interact handoff (opt-in)"
-  task :ssh_interact do
-    ruby "examples/ssh_interact.rb", "--auto"
-  end
-
-  desc "Automatically log into local SSH and run read-only macOS checks"
-  task :ssh_auto do
-    ruby "examples/ssh_auto.rb", "--no-interact"
-  end
-
-  desc "Run the local two-terminal kibitz scenarios and save logs (no SSH required)"
-  task :kibitz do
-    ruby "examples/kibitz/test_kibitz.rb"
-  end
-end

data/benchmark/matching.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "support"
-
-runner = ExpectBenchmark::Runner.new("matching")
-reader, writer = IO.pipe
-session = Expect.open(reader, log_stdout: false)
-begin
-  sizes = runner.smoke ? [4096] : [4096, 65_536, 1_048_576]
-  sizes.product([1, 8, 32], %i[first last miss]).each do |size, count, hit|
-    session.buffer = "#{"x" * (size - 3)}END"
-    patterns = Array.new(count) { |index| /missing#{index}/ }
-    index = hit == :first ? 0 : count - 1
-    patterns[index] = /END/ unless hit == :miss
-    matcher = Expect::Matcher.new(Expect::PatternList.new([session], patterns), 0)
-    verify = lambda do |result|
-      valid = if hit == :miss
-                result.nil?
-              else
-                result && result[0].equal?(session) && result[1].number == index + 1 && result[2] == [size - 3, 3, []]
-              end
-      ExpectBenchmark.check(valid)
-    end
-    runner.measure("scan/#{size}/#{count}/#{hit}", bytes: size, inputs: { size: size, patterns: count, hit: hit },
-                                                   verify: verify) { matcher.__send__(:find_match) }
-  end
-  sizes.each do |size|
-    prefix = "中" * (size / 3)
-    session.buffer = "#{prefix}😀终tail"
-    matcher = Expect::Matcher.new(Expect::PatternList.new([session], [/😀(终)(x)?/]), 0)
-    verify = lambda do |result|
-      ExpectBenchmark.check(result && result[2] == [prefix.bytesize, 7, ["终".b, nil]])
-    end
-    runner.measure("utf8/#{size}", bytes: session.buffer.bytesize, inputs: { prefix_bytes: prefix.bytesize },
-                                   verify: verify) { matcher.__send__(:find_match) }
-  end
-
-  # 同一次等待不断追加新字节，分别对照字面与正则；跨块命中仍按声明优先级选择。
-  (runner.smoke ? [4096] : [65_536, 1_048_576]).product(%i[literal regexp]).each do |size, kind|
-    chunks = runner.smoke ? 4 : 32
-    patterns = Array.new(32) { |index| "missing#{index}" }
-    patterns[-1] = "END"
-    patterns.map! { |value| Regexp.new(Regexp.escape(value)) } if kind == :regexp
-    verify = lambda do |result|
-      ExpectBenchmark.check(result && result[1].number == 32 && result[2] == [size + (chunks * 1024), 3, []])
-    end
-    runner.measure("stream/#{size}/#{kind}", bytes: size + (chunks * 1024) + 3,
-                                             inputs: { initial_bytes: size, chunks: chunks, patterns: 32, kind: kind },
-                                             iterations: 5, verify: verify) do
-      session.buffer = "x" * size
-      matcher = Expect::Matcher.new(Expect::PatternList.new([session], patterns), nil)
-      ExpectBenchmark.check(matcher.__send__(:find_match).nil?)
-      chunks.times do
-        writer.write("x" * 1024)
-        session.__send__(:read_available)
-        ExpectBenchmark.check(matcher.__send__(:find_match).nil?)
-      end
-      writer.write("END")
-      session.__send__(:read_available)
-      matcher.__send__(:find_match)
-    end
-  end
-ensure
-  session.close
-  reader.close
-  writer.close
-end
-
-[1, 8, 32].each do |count|
-  pipes = Array.new(count) { IO.pipe }
-  sessions = pipes.map { |input, _| Expect.open(input, log_stdout: false) }
-  begin
-    sessions.each { |source| source.buffer = "x" * 4096 }
-    list = Expect::PatternList.new
-    # 每轮交替反转来源组，确保同一会话真实出现在多个非相邻组。
-    8.times { |index| list.on(/missing/, from: index.even? ? sessions : sessions.reverse) }
-    # 单会话的相邻相同组会合并；保持普通单会话路径作为对照。
-    matcher = Expect::Matcher.new(list, 0)
-    runner.measure("groups/#{count}", bytes: 4096 * count, inputs: { sessions: count, groups: list.groups.size },
-                                      verify: lambda { |result|
-                                        ExpectBenchmark.check(result.nil?)
-                                      }) { matcher.__send__(:find_match) }
-    matcher.run
-    verify = lambda do |result|
-      ExpectBenchmark.check(result == :retry && sessions.all? { |source| source.buffer == "r" })
-    end
-    runner.measure("ready/#{count}", bytes: count, inputs: { sessions: count }, verify: verify) do
-      sessions.each(&:clear_buffer)
-      pipes.each { |pipe| pipe.last.write("r") }
-      ready = IO.select(pipes.map(&:first), nil, nil, 0).first
-      matcher.__send__(:read_ready, ready, sessions)
-    end
-  ensure
-    sessions.each(&:close)
-    pipes.flatten.each(&:close)
-  end
-end
-runner.finish

data/benchmark/redactor.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "support"
-
-# 同一驱动可加载基线或候选库；每轮创建独立过滤器，不能跨样本继承流状态。
-module RedactorBenchmark
-  def self.measure(runner, name, input, patterns, expected, chunk_size: nil, partial: false)
-    chunks = if chunk_size
-               (0...input.bytesize).step(chunk_size).map { |offset| input.byteslice(offset, chunk_size) }
-             else
-               [input]
-             end
-    runner.measure(name, bytes: input.bytesize,
-                         inputs: { bytes: input.bytesize, secret_lengths: patterns.map(&:bytesize),
-                                   chunk_size: chunk_size, partial: partial, repeated_finish: true },
-                         verify: ->(output) { ExpectBenchmark.check(output == expected, "incorrect #{name} output") },
-                         iterations: 5) do
-      filter = Expect::Redactor.new(patterns)
-      output = +"".b
-      chunks.each { |chunk| output << filter.append(chunk) }
-      output << filter.finish(partial: partial) << filter.finish(partial: partial)
-    end
-  end
-end
-
-runner = ExpectBenchmark::Runner.new("redactor")
-size = runner.smoke ? 512 : 65_536
-plain = "x" * size
-RedactorBenchmark.measure(runner, "empty_rules", plain, [], plain)
-RedactorBenchmark.measure(runner, "no_match", plain, ["secret"], plain)
-RedactorBenchmark.measure(runner, "no_match_many", plain, %w[secret password token credential], plain)
-RedactorBenchmark.measure(runner, "sparse", "#{plain}secret!", ["secret"], "#{plain}[FILTERED]!")
-RedactorBenchmark.measure(runner, "contiguous_short", "token" * (size / 5), ["token"], "[FILTERED]")
-
-(runner.smoke ? [1, 32, 128] : [1, 32, 1024, 4096]).each do |length|
-  RedactorBenchmark.measure(runner, "overlap_#{length}", "a" * size, ["a" * length], "[FILTERED]")
-end
-count = runner.smoke ? 8 : 256
-RedactorBenchmark.measure(runner, "contained_patterns", "abcde!" * count,
-                          %w[abc bc ab bcd], "[FILTERED]e!" * count)
-RedactorBenchmark.measure(runner, "binary_overlap", "\0\xffABC\x80!".b * count,
-                          ["\xffABC".b, "ABC\x80".b], "\0[FILTERED]!".b * count, chunk_size: 3)
-RedactorBenchmark.measure(runner, "marker_in_input", "[FILTERED] secret!" * count,
-                          %w[secret FILTERED], "[[FILTERED]] [FILTERED]!" * count)
-
-[1, 7, 4096].each do |chunk_size|
-  RedactorBenchmark.measure(runner, "stream_#{chunk_size}", "prefix secret!\n" * count,
-                            ["secret"], "prefix [FILTERED]!\n" * count, chunk_size: chunk_size)
-end
-[true, false].each do |partial|
-  RedactorBenchmark.measure(runner, "partial_#{partial}", "prefix pass", ["password"],
-                            partial ? "prefix [FILTERED]" : "prefix pass", chunk_size: 1, partial: partial)
-end
-
-runner.measure("update_pending", bytes: 10, inputs: { update: "keep old mask and match new secret" },
-                                 verify: lambda { |output|
-                                   ExpectBenchmark.check(output == "[FILTERED]!")
-                                 }, iterations: 100) do
-  filter = Expect::Redactor.new(%w[abc long-pattern])
-  output = filter.append("abcsec")
-  filter.patterns = ["secret"]
-  output << filter.append("ret!") << filter.finish << filter.finish
-end
-runner.finish

data/benchmark/relay.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "support"
-
-runner = ExpectBenchmark::Runner.new("relay")
-reader, writer = IO.pipe
-session = Expect.open(reader, log_stdout: false)
-begin
-  size = runner.smoke ? 4096 : 65_536
-  payload = "x" * size
-  %i[none literal regexps].each do |kind|
-    session.__send__(:sequences=, {})
-    session.on_sequence("STOP") if kind == :literal
-    16.times { |index| session.on_sequence(/missing#{index}/) } if kind == :regexps
-    output = StringIO.new("".b)
-    session.listeners = [output]
-    verify = ->(result) { ExpectBenchmark.check(result == true && output.string == payload) }
-    runner.measure("escape/#{kind}", bytes: size, inputs: { size: size, regexps: kind == :regexps ? 16 : 0 },
-                                     verify: verify) do
-      output.string = "".b
-      session.__send__(:relay_history).clear
-      Expect.__send__(:relay_buffer, session, { session => payload.b })
-    end
-  end
-
-  session.__send__(:sequences=, {})
-  writer.close
-  normal = StringIO.new("".b)
-  slow = StringIO.new("".b)
-  slow.define_singleton_method(:write) { |data| super(data.byteslice(0, 17)) }
-  session.listeners = [normal, slow]
-  verify = lambda do |result|
-    ExpectBenchmark.check(result.equal?(session) && normal.string == payload && slow.string == payload)
-    ExpectBenchmark.check(!session.pending_output? && session.buffer.empty?)
-  end
-  runner.measure("mixed_targets", bytes: size * 2, inputs: { size: size, short_write: 17 }, iterations: 5,
-                                  verify: verify) do
-    normal.string = "".b
-    slow.string = "".b
-    session.buffer = payload
-    Timeout.timeout(10) { Expect.interconnect(session, timeout: 5) }
-  end
-ensure
-  session.close
-  reader.close
-  writer.close unless writer.closed?
-end
-runner.finish

data/benchmark/scaling.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "support"
-
-counts = [1, 16, 64]
-runner = ExpectBenchmark::Runner.new("scaling") do |options|
-  options.on("--sessions N", Integer, "Measure one explicit session count (check the process fd limit)") do |count|
-    raise ArgumentError, "sessions must be positive" unless count.positive?
-
-    counts = [count]
-  end
-end
-counts = [1, 8] if runner.smoke
-counts.each do |count|
-  if (count * 2) + 32 > Process.getrlimit(:NOFILE).first
-    raise ArgumentError, "#{count} sessions need a larger process fd limit; run ulimit -n before this benchmark"
-  end
-
-  pipes = []
-  sessions = []
-  begin
-    count.times do
-      pipes << IO.pipe
-      sessions << Expect.open(pipes.last.first)
-    end
-    marker = "ready\n"
-    ready_count = 0
-    list = Expect::PatternList.new(sessions)
-    list.on(marker) do
-      ready_count += 1
-      Expect.continue(reset_timeout: false) if ready_count < count
-    end
-    verify = lambda do |result|
-      ExpectBenchmark.check(result.matched? && ready_count == count && sessions.all? { |source| source.buffer.empty? })
-    end
-    runner.measure("all_ready/#{count}", bytes: count * marker.bytesize, inputs: { sessions: count },
-                                         iterations: 10, verify: verify) do
-      ready_count = 0
-      pipes.each { |pipe| pipe.last.write(marker) }
-      Timeout.timeout(10) { Expect::Matcher.new(list, 5).run }
-    end
-  ensure
-    sessions.each(&:close)
-    pipes.flatten.each { |io| io.close unless io.closed? }
-  end
-end
-
-# 真实管道填满后完全不消费；另一个来源的标记仍须被读到，重复进入不能增长描述符。
-pipes = Array.new(3) { IO.pipe }
-slow = Expect.open(pipes[0].first)
-fast = Expect.open(pipes[1].first)
-sink = pipes[2].last
-begin
-  loop { break if sink.write_nonblock("x" * 4096, exception: false) == :wait_writable }
-  slow.listeners = [sink]
-  fast.on_sequence("PROBE")
-  verify = lambda do |result|
-    ExpectBenchmark.check(result.equal?(fast) && slow.pending_output? && fast.buffer.empty?)
-  end
-  runner.measure("blocked_target_probe", bytes: 5, inputs: { sources: 2, blocked_targets: 1 },
-                                         iterations: 100, verify: verify) do
-    slow.buffer = "blocked"
-    pipes[1].last.write("PROBE")
-    Timeout.timeout(10) { Expect.interconnect(slow, fast, timeout: 5) }
-  end
-ensure
-  [slow, fast].each(&:close)
-  pipes.flatten.each { |io| io.close unless io.closed? }
-end
-runner.finish

data/benchmark/send_slow.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "support"
-
-runner = ExpectBenchmark::Runner.new("send_slow")
-size = runner.smoke ? 8 : 128
-payload = "x" * size
-[false, true].product([0, 0.001]).each do |echo, delay|
-  verify = lambda do |result|
-    count, received, reply = result
-    ExpectBenchmark.check(count == size && received == payload && reply == (echo ? payload : nil))
-  end
-  runner.measure("send/#{echo ? "echo" : "silent"}/#{delay}", bytes: size,
-                                                              inputs: { size: size, echo: echo, delay: delay },
-                                                              iterations: 1, verify: verify) do
-    client, peer = Socket.pair(:UNIX, :STREAM, 0)
-    session = Expect.open(client, log_stdout: false)
-    consumer = Thread.new do
-      received = "".b
-      while received.bytesize < size
-        data = peer.readpartial(size)
-        received << data
-        peer.write(data) if echo
-      end
-      received
-    end
-    begin
-      Timeout.timeout(10) do
-        count = session.send_slow(payload, delay: delay)
-        reply = session.expect_result(payload, timeout: 2).match if echo
-        [count, consumer.value, reply]
-      end
-    ensure
-      consumer.kill.join
-      session.close
-      client.close
-      peer.close
-    end
-  end
-end
-runner.finish

data/benchmark/support.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "fileutils"
-require "optparse"
-require "open3"
-require "digest"
-require "socket"
-require "timeout"
-
-# 标准库基准入口；每个工作负载先验证结果，采样后再核对，计时不包含断言。
-module ExpectBenchmark
-  # 保存环境、输入规模、耗时、分配与 GC 样本，便于比较不同源码目录。
-  class Runner
-    attr_reader :smoke, :library
-
-    def initialize(name)
-      @library = File.expand_path("../lib", __dir__)
-      @samples = 5
-      @iterations = nil
-      @smoke = false
-      @output = "tmp/benchmark/#{name}.json"
-      OptionParser.new do |options|
-        options.banner = "Usage: ruby benchmark/#{name}.rb [options]"
-        options.on("--smoke", "Small correctness workload") { @smoke = true }
-        options.on("--library PATH", "Compare another checkout's lib directory") do |path|
-          @library = File.expand_path(path)
-        end
-        options.on("--samples N", Integer) { |count| @samples = count }
-        options.on("--iterations N", Integer) { |count| @iterations = count }
-        options.on("--output PATH") { |path| @output = path }
-        yield options if block_given?
-      end.parse!
-      unless @samples.positive? && (!@iterations || @iterations.positive?)
-        raise ArgumentError, "counts must be positive"
-      end
-
-      require File.join(@library, "expect")
-      @results = []
-    end
-
-    def measure(name, bytes:, inputs:, verify:, iterations: 100, &operation)
-      iterations = @iterations || (smoke ? 1 : iterations)
-      samples = smoke ? 1 : @samples
-      verify.call(operation.call) # 同时预热；错误输出永远不能成为更快的样本。
-      measurements = Array.new(samples) do
-        GC.start
-        resources_before = resources
-        before = GC.stat
-        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        result = nil
-        iterations.times { result = operation.call }
-        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
-        after = GC.stat
-        verify.call(result)
-        {
-          seconds: elapsed, allocated_objects: after[:total_allocated_objects] - before[:total_allocated_objects],
-          gc_count: after[:count] - before[:count], processed_bytes: bytes * iterations,
-          resources_before: resources_before, resources_after: resources
-        }
-      end
-      @results << { name: name, inputs: inputs, iterations: iterations, samples: measurements }
-      puts "#{name}: #{format("%.6f", measurements.map { |row| row[:seconds] }.sort[samples / 2])}s"
-    end
-
-    def finish
-      root = File.dirname(library)
-      repository = git_output(root, "rev-parse", "--show-toplevel")&.strip
-      if repository && File.realpath(repository) == File.realpath(root)
-        sha = git_output(root, "rev-parse", "HEAD")
-        dirty = git_output(root, "status", "--porcelain", "--untracked-files=all")
-      end
-      digest = Digest::SHA256.new
-      Dir[File.join(library, "**/*.rb")].each do |path|
-        digest << path.delete_prefix(library) << File.binread(path)
-      end
-      report = {
-        ruby: RUBY_DESCRIPTION, platform: RUBY_PLATFORM, revision: sha&.strip,
-        fd_limit: Process.getrlimit(:NOFILE).first,
-        dirty: dirty.nil? ? nil : !dirty.empty?, library_sha256: digest.hexdigest, smoke: smoke, results: @results
-      }
-      FileUtils.mkdir_p(File.dirname(@output))
-      File.write(@output, "#{JSON.pretty_generate(report)}\n")
-      puts "Saved #{@output}"
-    end
-
-    private
-
-    # 资源采样在计时区间之外；RSS 是端点值，不冒充峰值。目录不可用时显式记录 nil。
-    def resources
-      directory = File.directory?("/proc/self/fd") ? "/proc/self/fd" : "/dev/fd"
-      descriptors = Dir.children(directory).size if File.directory?(directory)
-      rss = if File.file?("/proc/self/status")
-              File.read("/proc/self/status")[/^VmRSS:\s+(\d+)/, 1]&.to_i
-            else
-              output, _, status = Open3.capture3("ps", "-o", "rss=", "-p", Process.pid.to_s)
-              output.to_i if status.success?
-            end
-      { rss_bytes: rss && (rss * 1024), descriptors: descriptors }
-    end
-
-    # 安装包和源码归档可能没有 Git；未知状态记录为 nil，不误报为干净提交。
-    def git_output(root, *)
-      output, _, status = Open3.capture3("git", "-C", root, *)
-      output if status.success?
-    rescue Errno::ENOENT
-      nil
-    end
-  end
-
-  def self.check(condition, message = "incorrect benchmark output")
-    raise message unless condition
-  end
-end

data/docs/COMPATIBILITY.md

@@ -1,98 +0,0 @@
-# Ruby 接口与 Expect 行为对照
-
-## Tcl Expect 语义边界
-
-参考 Tcl Expect 的[官方手册](https://core.tcl-lang.org/expect/doc/trunk/expect.man)、
-[`expect.c`](https://core.tcl-lang.org/expect/raw/expect.c?ci=trunk) 的 `eval_cases` / `expMatchProcess` / 计时循环，
-以及 [`exp_inter.c`](https://core.tcl-lang.org/expect/raw/exp_inter.c?ci=trunk) 的 `intMatch` 与终端恢复流程。
-本库借鉴交互模型，保留以下明确差异，不承诺 Tcl 脚本或完整功能兼容。
-
-| Tcl Expect 能力                       | 本库的 Ruby 表达与边界                                                                                                              |
-|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
-| `spawn`、`send`、`expect`、`interact` | PTY 会话、`write` / `puts`、原生模式块和人工接管；`send` 保留 Ruby 反射语义                                                         |
-| `exp_continue` / `-continue_timer`    | `continue` / `continue(reset_timeout: false)`；使用单调时钟和秒数关键字参数                                                         |
-| 匹配后消费输入、`-notransfer`         | `before` / `match` / `after` 与会话级 `preserve_buffer`；无进展回调不会原地重复执行                                                 |
-| glob、exact、regexp 模式              | 字符串只作字面匹配，正则采用 Ruby `Regexp`；锚点和多行行为遵守 Ruby                                                                 |
-| `match_max`、`full_buffer`            | `buffer_limit` 只保留尾部字节，默认无限；`buffer_discarded_bytes` 统计累计裁剪量，无缓冲满事件                                         |
-| 前置/后置模式、后台匹配               | 没有全局隐式规则或后台读取器；调用方显式组合模式块，每个会话由一个读取者驱动                                                        |
-| `interact` 的部分正则匹配             | Tcl 的 `CANMATCH` 可以暂存潜在匹配；Ruby 原生正则不提供该接口，本库使用有限历史窗口，已转发前缀不能撤回。需要完整过滤时使用字面转义 |
-| `close` 与 `wait`                     | IO 结束与进程退出仍分开判断；本库的块生命周期和 `close` 会额外回收直属子进程                                                        |
-
-长输出任务应通过日志或监听器流式保存，并按提示长度设置 `buffer_limit`。只读 `buffer_discarded_bytes` 提供会话累计裁剪字节数，正常匹配消费和清空不计入；它不是无损缓冲满事件。后台匹配与共享前置/后置模式也需要独立的取消、优先级和资源归属约定，尚未实现。
-
-`expect` / `expect_result` 的 `deadline:` 是额外的绝对单调时钟总期限，限制相对 `timeout` 的所有重置，不改变已知 EOF 派发和未指定总期限时的零超时轮询。会话 `diagnostic_output` 与接收日志独立；显式 `redact` 仅过滤日志和诊断，协议转发与匹配仍使用原始字节。
-
-## Expect.pm 接口迁移
-
-交互能力参考 [jacoby/expect.pm](https://github.com/jacoby/expect.pm)，源码基准为版本 1.38、提交
-`2ea0e4ce20a896c95cb4c94e781f1b1f3145150d`。此项目独立实现，使用 MIT 许可，没有复制 Perl 实现代码；原项目作者及维护者为
-Austin Schutz、Roland Giersig、Dave Jacoby，采用与 Perl 相同的许可。
-
-从 0.2.0 起采用 Ruby 原生接口。下表列出迁移关系， **旧方法、别名和参数语法已移除**；历史 0.1.1 安装包的接口见对应版本记录。
-
-| 原接口或状态                               | 当前 Ruby 接口                                                      |
-|--------------------------------------------|---------------------------------------------------------------------|
-| 包级默认值、`Expect.defaults`              | `Expect.configure { \|config\| ... }`、冻结的 `Expect.configuration` |
-| `timeout(10)` 等读写合一方法               | `timeout`、`timeout = 10`；布尔查询使用 `name?`                     |
-| `exp_init`、`init`                         | `Expect.open(io, writer:, own:)`，支持块生命周期                    |
-| `expect(seconds, ...)`                     | `expect(..., timeout: seconds)`；完整结果使用 `expect_result`       |
-| `-ex`、`-re`、数组字符串正则               | 字符串字面匹配，正则使用原生 `Regexp`                               |
-| `-i` 分组                                  | `from: session` / `from: [sessions]`，或块内 `on(..., from:)`       |
-| `[pattern, callback, *args]`               | `on(pattern) { \|session\| ... }`，附加参数使用闭包 |
-| `exp_continue`、`exp_continue_timeout`     | `continue`、`continue(reset_timeout: false)`                        |
-| 数字前缀错误字符串                         | `Result#error` 为 `:timeout`、`:eof` 或原始 IO 异常对象             |
-| `matchlist`、`exp_matchlist`               | `captures`                                                          |
-| `exp_pid`、`exp_match` 等别名              | `pid`、`match` 等属性                                               |
-| `get_accum`、`set_accum`、`clear_accum`    | `buffer`、`buffer=`、`clear_buffer`                                 |
-| `max_accum`、`match_max`                   | `buffer_limit`，正整数；`nil` 表示无限                              |
-| `notransfer`                               | `preserve_buffer`                                                   |
-| `restart_timeout_upon_receive`             | `reset_timeout_on_read`                                             |
-| `log_user`、`log_group`                    | `log_stdout`、`log_listeners`                                       |
-| `log_file`、`logfile`、`exp_logfile`       | `log_output` / `log_output=`；路径和日志块使用 `log_to(..., mode:)` |
-| `print_log_file`                           | `write_log`                                                         |
-| `set_group`                                | `listeners` / `listeners=`                                          |
-| `set_seq(sequence, callback, args)`        | `on_sequence(sequence) { ... }`                                     |
-| `send`、`print`                            | `write` 原样写入、`puts` 按行输出；`send` 保留 Ruby 反射语义        |
-| `send_slow(delay, *strings)`、`write_slow` | `send_slow(*objects, delay:)`                                       |
-| `manual_stty = true`                       | `raw_terminal = false`；`stty` 保留，`exp_stty` 移除                |
-| `interact(input, escape)`                  | `interact(input:, escape:, output:, timeout:)`                      |
-| `test_handles` 的索引数组                  | `readable_sessions(*sessions, timeout:)` 返回会话对象数组           |
-| `wait(seconds)`                            | `wait(timeout: seconds)`，返回 `Process::Status`                    |
-| `exitstatus`、`exp_exitstatus` 原始整数    | `process_status.to_i`；普通退出码用 `exit_code`                     |
-| `do_soft_close`                            | `graceful_close`，可通过 `close(graceful:)` 单次覆盖                |
-| `debug`、`exp_internal`                    | `debug_level`，整数 `0..3`                                          |
-| `ttyname`、`pty_handle`                    | `tty_name`、标准 `inspect`                                          |
-| `version`                                  | 常量 `Expect::VERSION`                                              |
-| `multiline_matching`                       | 原生正则的 `^` / `$`、`\A` / `\z` 和 `/m`                           |
-| `ignore_eintr`                             | 匹配等待自动重试 EINTR，并保留原期限                                |
-
-## 保留的交互能力
-
-仍支持真实控制终端、精确/正则匹配、模式优先级、捕获组、二进制与分片
-UTF-8、EOF/超时回调、绝对期限与接收重置、多会话、缓冲上限、慢速写入和背压、路径/IO/回调日志、监听组、人工接管、跨读取转义及终端恢复。
-
-`expect` 返回模式序号或 `nil`；`expect_result` / `last_result` 返回原生七字段 `Struct`。`to_a`、`to_h`、模式解构使用 Ruby
-自带行为，多重赋值需要显式 `result.to_a`。日志按实际读取时记录，转接与匹配切换不重复写日志；显式启用 `redact` 时过滤已注册秘密。
-
-## 软关闭与硬关闭
-
-参考原版的策略边界：`soft_close` 先收集剩余输出，关闭所属句柄，等待退出并最多发送 TERM； **不发送 KILL**。未退出返回 `nil`，保留
-PID。`hard_close` 不等待输出，必要时 TERM、KILL 并回收子进程。关闭会话 IO 不代表子进程已经退出。
-
-Ruby 使用关键字指定各阶段期限，关闭方法返回 `Process::Status` 或 `nil`。`close(graceful: true)` 和 `graceful_close = true`
-先尝试软关闭，再在 `ensure` 中硬关闭；这对应原版销毁时可选软关闭、随后硬关闭的清理策略。`close` 返回 `nil`；GC
-兜底直接强制清理，不阻塞等待。
-
-## 有意采用的 Ruby 语义
-
-- 默认关闭 stdout 输出，显式启用 `log_stdout`。配置按会话隔离，构造参数覆盖全局默认；配置异常不发布部分状态。
-- 仅 `nil` 和 `false` 为假，`0` 为真。转接回调也采用此规则。
-- 字符串始终是字面文本；只有 `:eof` / `:timeout` 是事件，`"EOF"` 是普通转义文本。
-- 超时回调接收所有仍在监听的会话；重复注册超时回调抛出 `ArgumentError`。
-- `write` 返回字节数，`puts` 返回 `nil`，`<<` 返回会话。
-- 启动失败抛出 `Expect::SpawnError` 并回收；EOF 不主动终止仍存活的进程。借用 IO 不关闭，接管 IO 在初始化失败或会话关闭时释放。
-- Perl 特有的正则、IO::Pty 继承 API、全局信号 handler 和 Solaris 字节删除补丁不移植。Ruby 使用 `to_io`、`slave`、`io/console`
-  和原生正则。
-
-`test/compare_upstream.rb` 仅对共同的交互行为作可选差分验证，通过 Ruby 新接口表达同样场景，并显式转换错误标记和可读会话索引；它不要求或证明旧
-API 兼容，也不等于运行完整上游测试套件。