expect-pty 0.2.0

data/lib/expect/pattern.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Expect
+  # 一个已编号的文本模式或事件及其回调；匹配结果统一使用字节偏移，便于精确消费 IO 缓冲。
+  Pattern = Struct.new(:number, :value, :callback, keyword_init: true) do
+    # 将匹配会话或超时会话数组交给回调；额外上下文由调用方闭包保存。
+    def call(subject)
+      callback&.call(subject)
+    end
+
+    # 识别 EOF 事件，供引擎在源结束时单独派发。
+    def eof? = value == :eof
+
+    # 在缓冲中定位字符串或正则，返回 [字节偏移, 字节长度, 捕获组]；事件或未匹配返回 nil。
+    def locate(buffer)
+      case value
+      when String
+        offset = buffer.index(value)
+        return [offset, value.bytesize, []] if offset
+      when Regexp
+        text = buffer.dup
+        text.force_encoding(value.encoding) if value.fixed_encoding?
+        unless text.valid_encoding?
+          # 一次读取可能截断 UTF-8 字符。仅对完整前缀做本轮匹配，原缓冲保留残片等待后续字节。
+          text = complete_prefix(text)
+        end
+        found = value.match(text)
+        return unless found
+
+        # Ruby 正则偏移按字符计算，缓冲切片按字节计算，必须转换；捕获组也统一返回字节串。
+        offset = text[0...found.begin(0)].bytesize
+        return [offset, found[0].bytesize, found.captures.map { |capture| capture&.b }]
+      end
+      nil
+    end
+
+    private
+
+    # 仅容忍末尾尚未收全的 UTF-8 字符，其他非法编码直接报错，不静默替换接收字节。
+    def complete_prefix(text)
+      if text.encoding == Encoding::UTF_8
+        # UTF-8 字符最多四字节，不完整后缀最多三字节。逐一验证头字节、续字节及剩余前缀。
+        1.upto([3, text.bytesize].min) do |length|
+          prefix = text.byteslice(0, text.bytesize - length)
+          suffix = text.byteslice(text.bytesize - length, length).b
+          lead = suffix.getbyte(0)
+          expected = case lead
+                     when 0xC2..0xDF then 2
+                     when 0xE0..0xEF then 3
+                     when 0xF0..0xF4 then 4
+                     end
+          if expected && length < expected && suffix.bytes.drop(1).all? do |byte|
+            (0x80..0xBF).cover?(byte)
+          end && prefix.valid_encoding?
+            return prefix
+          end
+        end
+      end
+      raise EncodingError, "received invalid #{text.encoding} data; use a binary regexp (/.../n) for binary streams"
+    end
+  end
+end

data/lib/expect/pattern_list.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+class Expect
+  # 将 Ruby 模式和块回调整理为有序会话组；注册阶段不读取 IO、不执行匹配回调。
+  class PatternList
+    attr_reader :groups, :timeout_pattern
+
+    # 建立默认来源，并将位置参数中的文本、正则、:eof、:timeout 转成统一模式。
+    def initialize(sessions = [], patterns = [])
+      @default_sessions = Array(sessions).dup
+      validate_sessions!(@default_sessions) unless @default_sessions.empty?
+      # 保留空模式的默认会话组，使 expect(timeout:) 也能只收集输出而不匹配文本。
+      @groups = @default_sessions.empty? ? [] : [[@default_sessions, []]]
+      @number = 0
+      patterns.each do |value|
+        case value
+        when :eof then eof
+        when :timeout then timeout
+        else on(value)
+        end
+      end
+    end
+
+    # 注册文本模式；字符串始终字面匹配并复制冻结，避免注册后被外部修改。
+    def on(value, from: @default_sessions, &block)
+      raise ArgumentError, "pattern must be a String or Regexp" unless value.is_a?(String) || value.is_a?(Regexp)
+
+      add(value.is_a?(String) ? value.b.freeze : value, from, block)
+    end
+
+    # 为指定来源注册 EOF 回调；实例 DSL 默认使用当前会话。
+    def eof(from: @default_sessions, &block)
+      add(:eof, from, block)
+    end
+
+    # 注册一次等待的唯一超时回调，重复定义直接报错，避免悄悄覆盖业务处理。
+    def timeout(&block)
+      raise ArgumentError, "timeout callback already registered" if @timeout_pattern
+
+      @timeout_pattern = build(:timeout, block)
+      self
+    end
+
+    # 汇总并去重读取源，同一会话出现在多个模式组时仍只读取一次。
+    def sessions = groups.flat_map(&:first).uniq
+
+    # 收集指定会话的所有 EOF 处理器，保留原注册顺序。
+    def eof_patterns_for(session)
+      groups.flat_map do |sessions, patterns|
+        sessions.include?(session) ? patterns.select(&:eof?) : []
+      end
+    end
+
+    # 启动引擎前确保存在读取源；类级等待必须通过 from: 明确来源。
+    def validate!
+      raise ArgumentError, "at least one session is required" if groups.empty?
+
+      self
+    end
+
+    private
+
+    # 校验并复制来源列表，将模式加入相邻的相同来源组或新建组。
+    def add(value, from, callback)
+      sessions = Array(from).dup
+      validate_sessions!(sessions)
+      pattern = build(value, callback)
+      # 仅合并相邻的相同来源，保持声明顺序；跨组复用会话由引擎去重读取。
+      if groups.last&.first == sessions
+        groups.last.last << pattern
+      else
+        groups << [sessions, [pattern]]
+      end
+      self
+    end
+
+    # 按注册顺序分配从 1 开始的序号，文本模式与事件共用编号。
+    def build(value, callback)
+      @number += 1
+      Pattern.new(number: @number, value: value, callback: callback)
+    end
+
+    # 拒绝空来源和非 Expect 对象，在任何 IO 读取之前暴露调用错误。
+    def validate_sessions!(sessions)
+      return if !sessions.empty? && sessions.all?(Expect)
+
+      raise ArgumentError, "patterns require Expect sessions; specify from: for class-level waits"
+    end
+  end
+end

data/lib/expect/pty.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# 提供明确的 Gem 加载入口，避免与 Ruby 标准库 expect.rb（IO#expect 扩展）同名冲突。
+require_relative "../expect"

data/lib/expect/resources.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class Expect
+  # 独立保存句柄、PID 和日志所有权，让终结器无需直接捕获会话即可清理遗弃资源。
+  class Resources
+    attr_accessor :pid, :status, :log, :own_log
+    attr_reader :reader, :writer, :slave, :owner, :own
+
+    # 记录创建资源的进程；fork 后的副本不能向父进程拥有的子进程发信号。
+    def initialize(reader, writer:, slave: nil, own: false)
+      @reader = reader
+      @writer = writer
+      @slave = slave
+      @own = own
+      @owner = Process.pid
+    end
+
+    # 只关闭由本库拥有的 IO；借用的 reader、writer 由调用方管理。
+    def close_handles
+      return unless own
+
+      # PTY 的读写端可能是同一个对象，先去重，重复关闭也保持安全。
+      [reader, writer, slave].compact.uniq.each { |io| io.close unless io.closed? }
+    end
+
+    # 非阻塞回收直属子进程，缓存 Process::Status，成功后清空 PID 以支持重复查询。
+    def reap
+      return status unless pid && owner == Process.pid
+
+      if (reaped = Process.waitpid2(pid, Process::WNOHANG))
+        @status = reaped.last
+        @pid = nil
+      end
+      status
+    rescue Errno::ECHILD
+      # 子进程可能已被调用方或其他线程回收，不再保留可能被系统复用的 PID。
+      @pid = nil
+      status
+    end
+
+    # GC 兜底关闭所属句柄和日志，并强制终止尚存活的子进程；不执行软关闭等待。
+    def finalize
+      return unless owner == Process.pid
+
+      close_handles
+      log.close if own_log && log && !log.closed?
+      reap
+      return unless pid
+
+      Process.kill("KILL", pid)
+      # 将最终 wait 交给后台回收线程，避免在 GC 终结器中阻塞等待。
+      Process.detach(pid)
+      @pid = nil
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    # 构造只持有资源对象的终结回调，避免闭包中的 self 绑定到会话而妨碍回收。
+    def self.finalizer(resources)
+      proc { resources.finalize }
+    end
+  end
+end

data/lib/expect/result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Expect
+  # 保存一次等待的结果，保留 Struct 原生数组、Hash 转换和模式解构能力。
+  # number 仅在文本匹配时存在；error 为 :timeout、:eof 或原始 IO 异常，文本字段均为字节串。
+  Result = Struct.new(:number, :error, :match, :before, :after, :session, :captures, keyword_init: true) do
+    # 是否命中文本模式；事件不会返回模式序号。
+    def matched? = !number.nil?
+    # 是否因本次等待期限到达而返回。
+    def timeout? = error == :timeout
+    # 是否读取源已经结束；子进程是否退出仍应查询会话的 process_status。
+    def eof? = error == :eof
+  end
+end

data/lib/expect/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class Expect
+  # Gem 与库共用的版本号；独立文件使 gemspec 无需加载完整会话实现。
+  VERSION = "0.2.0"
+end