expect-pty 0.5.3 → 0.7.1

data/lib/expect/logging.rb

@@ -1,200 +1,155 @@
 # frozen_string_literal: true
 
+require "logger"
 require_relative "redactor"
 
-# 管理日志目标、监听器及同步输出；资源所有权仍由会话的 SessionResources 统一保存。
-# 接收日志、诊断和协议转发是三条独立通道；脱敏只改变前两条，不改变匹配或转发字节。
-class Expect
-  # 读取当前日志目标，可能为库打开的文件、借用的 IO、回调或 nil。
-  attr_reader :log_output, :diagnostic_output
-
-  # 诊断目标仅借用；nil 沿用 stderr，Logger 使用 info/debug，回调接收冻结的事件 Hash。
-  # 先校验再冲刷旧流；校验或冲刷失败时保留旧目标，避免把暂存尾部交给错误的接收方。
-  def diagnostic_output=(target)
-    unless target.nil? || (target.respond_to?(:info) && target.respond_to?(:debug)) ||
-           target.respond_to?(:write) || target.respond_to?(:call)
-      raise ArgumentError, "diagnostic output must support info/debug, write or call, or be nil"
+# 借用标准 Logger、接收记录 writer 和协议输出 writer，不接管它们的生命周期。
+# 脱敏只作用于诊断与接收记录，协议输出和匹配缓冲始终保留原始字节。
+module Expect
+  # 会话诊断、接收记录和协议转发的独立输出接口。
+  # 宿主 Session 初始化目标与过滤器状态，并提供 pid、fileno 作为诊断元数据。
+  # 三种输出各有边界：Logger 接收事件，transcript 接收脱敏字节，outputs 接收原协议字节。
+  module Logging
+    # 调用方提供的诊断 Logger 与原始接收记录 writer，均由调用方管理生命周期。
+    attr_reader :logger, :transcript
+
+    # Logger 自己决定级别、格式与失败策略；nil 禁用诊断，不隐式写入 stderr。
+    # 替换前先完成旧流脱敏，失败时仍保留旧 logger。
+    def logger=(target)
+      unless target.nil? || (target.respond_to?(:add) && target.respond_to?(:debug?))
+        raise ArgumentError, "logger must support add and debug?, or be nil"
+      end
+      return if @logger.equal?(target)
+
+      flush_diagnostics
+      @logger = target
+      @diagnostic_redactors = {}
     end
-    return if @diagnostic_output.equal?(target)
 
-    flush_diagnostics
-    @diagnostic_output = target
-  end
+    # 秘密仅作用于本会话的接收记录和诊断，不改写匹配或 outputs 的协议字节。
+    # 先校验全部值再发布；注册是追加操作，应在首次通信前完成，不能追溯已交付的日志。
+    def redact(*secrets)
+      unless secrets.any? && secrets.all? { |secret| secret.is_a?(String) && !secret.empty? }
+        raise ArgumentError, "secrets must be nonempty Strings"
+      end
 
-  # 秘密仅作用于本会话的日志和诊断，不改写匹配、stdout 显示或 listeners 的协议字节。
-  # 先校验全部值再发布；注册是追加操作，应在首次通信前完成，不能追溯已交付的日志。
-  def redact(*secrets)
-    unless secrets.any? && secrets.all? { |secret| secret.is_a?(String) && !secret.empty? }
-      raise ArgumentError, "secrets must be nonempty Strings"
+      @secrets = ((@secrets || []) + secrets.map { |secret| secret.b.freeze }).uniq.freeze
+      @transcript_redactor.patterns = @secrets if @transcript_redactor
+      @diagnostic_redactors.each_value { |redactor| redactor.patterns = @secrets }
+      self
     end
 
-    @secrets = ((@secrets || []) + secrets.map { |secret| secret.b.freeze }).uniq.freeze
-    @log_redactor.patterns = @secrets if @log_redactor
-    @diagnostic_redactors&.each_value { |redactor| redactor.patterns = @secrets }
-    self
-  end
+    # 接收记录只采用 write 协议；文件打开、权限和关闭由调用方管理。
+    def transcript=(target)
+      raise ArgumentError, "transcript must support write, or be nil" unless target.nil? || target.respond_to?(:write)
+      return if @transcript.equal?(target)
 
-  # 替换借用的日志目标或停止日志；先校验新目标，失败时保留旧目标。
-  def log_output=(target)
-    unless target.nil? || target.respond_to?(:write) || target.respond_to?(:call)
-      raise ArgumentError, "log output must support write or call, or be nil"
+      flush_transcript
+      @transcript = target
+      @transcript_redactor = nil
     end
 
-    replace_log(target)
-  end
+    # 向接收记录补写内容，不发送给子进程或 outputs；脱敏尾部可能延迟交付，返回 nil。
+    def write_transcript(*objects)
+      target = transcript
+      return unless target
 
-  # 打开追加/覆盖日志文件，或注册接收字节的日志块；同一次只能指定一种目标。
-  def log_to(target = nil, mode: "a", &block)
-    raise ArgumentError, "provide a log target or a block, not both" if block && target
+      data = objects.map { |object| object.to_s.b }.join
+      if @secrets
+        @transcript_redactor ||= Redactor.new(@secrets)
+        data = @transcript_redactor.append(data)
+        return if data.empty?
+      end
+      emit(target, data)
+      nil
+    end
 
-    target = block if block
-    if target.respond_to?(:to_path) || target.is_a?(String)
-      raise ArgumentError, "log mode must be a or w" unless %w[a w].include?(mode)
+    # 返回副本，避免外部原地修改转发关系；stdout 与其他 writer 使用相同协议。
+    def outputs = @outputs.dup
 
-      # 先交付旧过滤尾部，再允许新路径截断；同一文件不能在截断后被旧句柄写回。
-      flush_log
-      # 库打开的文件由 SessionResources 持有，替换日志或关闭会话时释放；外部 IO 只借用。
-      replace_log(File.open(target, "#{mode}b", 0o600), owned: true)
-    else
-      raise ArgumentError, "provide a log target or a block" unless target
+    # 先校验整个数组再替换，失败时保留原输出图。
+    def outputs=(targets)
+      unless targets.is_a?(Array) && targets.all? { |target| target.respond_to?(:write) }
+        raise ArgumentError, "outputs must be an Array of writers"
+      end
 
-      self.log_output = target
+      @outputs = targets.dup
     end
-  end
 
-  # 向当前日志目标补写内容，支持 IO 和回调，不发送给子进程或监听器。
-  # 启用脱敏后可能暂存末尾字节，因此一次调用不保证触发一次日志写入或回调。
-  def write_log(*objects)
-    target = log_output
-    return unless target
-
-    data = objects.map { |object| object.to_s.b }.join
-    if @secrets
-      @log_redactor ||= Redactor.new(@secrets)
-      data = @log_redactor.append(data)
-      return if data.empty?
+    # 原样转发协议字节，接收记录在读取时单独写入。
+    # @api private
+    def propagate(data)
+      @outputs.each { |output| emit(output, data) }
     end
-    target.respond_to?(:call) ? target.call(data) : emit(target, data)
-  end
-
-  # 返回监听器列表副本，避免外部原地修改转发关系。
-  def listeners = @listeners.dup
-
-  # 校验所有监听器均可写后一次性替换列表，外部数组后续修改不会影响会话。
-  def listeners=(outputs)
-    outputs = Array(outputs)
-    raise ArgumentError, "listeners must support write" unless outputs.all? { |output| output.respond_to?(:write) }
-
-    @listeners = outputs.dup
-  end
 
-  private
+    private
 
-  # 按各自开关将接收字节转发到 stdout 和监听器，不重复写日志。
-  def propagate(data)
-    emit($stdout, data) if log_stdout?
-    @listeners.each { |listener| emit(listener, data) } if log_listeners?
-  end
+    # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
+    # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
+    # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。
+    def emit(target, data)
+      offset = 0
+      while offset < data.bytesize
+        count = target.write(data.byteslice(offset..))
+        unless count.is_a?(Integer) && count.positive? && count <= data.bytesize - offset
+          raise IOError, "write must return the number of accepted bytes"
+        end
 
-  # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
-  # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
-  # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。
-  def emit(target, data)
-    offset = 0
-    while offset < data.bytesize
-      count = target.write(data.byteslice(offset..))
-      unless count.is_a?(Integer) && count.positive? && count <= data.bytesize - offset
-        raise IOError, "write must return the number of accepted bytes"
+        offset += count
       end
-
-      offset += count
+      target.flush if target.respond_to?(:flush)
     end
-    target.flush if target.respond_to?(:flush)
-  end
 
-  # 字节诊断在 inspect 转义之前过滤；缓冲快照可能只含秘密中间片段，启用脱敏时不展开。
-  def trace_data(event, data, level:)
-    if @secrets
-      return trace("buffer [FILTERED]", level: level, event: event) if event == :buffer
+    # 字节诊断在 inspect 转义之前过滤，发送与接收各自保留分片状态。
+    def trace_data(event, data)
+      return unless logger&.debug?
 
-      @diagnostic_redactors ||= {}
-      redactor = (@diagnostic_redactors[event] ||= Redactor.new(@secrets))
-      data = redactor.append(data)
-      return if data.empty?
+      if @secrets
+        redactor = (@diagnostic_redactors[event] ||= Redactor.new(@secrets))
+        data = redactor.append(data)
+        return if data.empty?
+      end
+      trace("#{event} #{data.inspect}", severity: Logger::DEBUG, event:)
     end
-    trace("#{event} #{data.inspect}", level: level, event: event)
-  end
 
-  # 诊断与接收字节日志分开；回调元数据不含会话对象，避免格式化时意外展开原始缓冲。
-  def trace(message, level: 1, event: :matched)
-    return unless debug_level >= level
-
-    severity = level == 1 ? :info : :debug
-    target = diagnostic_output
-    if target.respond_to?(:info) && target.respond_to?(:debug)
-      target.public_send(severity, "#{inspect}: #{message}")
-    elsif target.respond_to?(:call)
-      target.call({ event: event, level: severity, pid: pid, fd: fileno, message: message.freeze }.freeze)
-    elsif target
-      emit(target, "#{inspect}: #{message}\n")
-    else
-      warn("#{inspect}: #{message}")
+    # 向标准 Logger 提交不可变事件，不包含会话对象；格式化由 logger 完成。
+    def trace(message, severity: Logger::INFO, event: :matched)
+      logger&.add(severity, { event:, pid:, fd: fileno, message: message.freeze }.freeze, "Expect")
     end
-  end
 
-  # 结束当前日志片段并交付过滤器尾部；重复调用不会重放已释放字节，写入异常原样传播。
-  def flush_log
-    loop do
-      return unless @log_redactor && log_output
+    # 结束当前日志片段并交付过滤器尾部；重复调用不会重放已释放字节，写入异常原样传播。
+    def flush_transcript
+      loop do
+        return unless @transcript_redactor && transcript
 
-      data = @log_redactor.finish
-      return if data.empty?
+        data = @transcript_redactor.finish
+        return if data.empty?
 
-      log_output.respond_to?(:call) ? log_output.call(data) : emit(log_output, data)
-      # 回调可能轮换目标并追加新尾部；先结束它，再允许外层截断文件或关闭日志。
+        emit(transcript, data)
+        # writer 可能重入并追加尾部；交接前仍归当前记录流。
+      end
     end
-  end
-
-  # EOF 只结束接收诊断；目标替换或显式关闭结束全部方向，发送与接收不能拼成一个秘密。
-  # GC 终结器不进入本方法，避免在回收阶段调用用户回调或持有会话对象。
-  def flush_diagnostics(event = nil)
-    return unless @diagnostic_redactors
-
-    loop do
-      delivered = false
-      # 回调可能首次创建另一个方向，也可能写入本轮已经处理的方向。
-      @diagnostic_redactors.to_a.each do |name, redactor|
-        next if event && name != event
 
-        data = redactor.finish
-        next if data.empty?
-
-        delivered = true
-        trace("#{name} #{data.inspect}", level: 2, event: name)
+    # EOF 只结束接收诊断；目标替换或显式关闭结束全部方向，发送与接收不能拼成一个秘密。
+    # GC 终结器不进入本方法，避免在回收阶段调用用户回调或持有会话对象。
+    def flush_diagnostics(event = nil)
+      return unless @diagnostic_redactors
+
+      loop do
+        delivered = false
+        # 回调可能首次创建另一个方向，也可能写入本轮已经处理的方向。
+        @diagnostic_redactors.to_a.each do |name, redactor|
+          next if event && name != event
+
+          data = redactor.finish
+          next if data.empty?
+
+          delivered = true
+          trace("#{name} #{data.inspect}", severity: Logger::DEBUG, event: name)
+        end
+        # 目标尚未交接，新产生的尾部仍归旧诊断流；排空后才结束这次冲刷。
+        break unless delivered
       end
-      # 目标尚未交接，新产生的尾部仍归旧诊断流；排空后才结束这次冲刷。
-      break unless delivered
     end
   end
-
-  # 交接日志目标和所有权，只关闭库拥有的旧文件；失败时释放新打开的文件。
-  def replace_log(target, owned: false)
-    # 重复赋值同一目标时保留原所有权，防止将库打开的文件误变成借用资源。
-    return target if log_output.equal?(target)
-
-    flush_log
-    # 尾部回调可以重入并替换目标；交接时重新读取目标和所有权，不能关闭旧的回调对象。
-    return target if log_output.equal?(target)
-
-    previous = @resources.owned_log
-    previous.close if previous && !previous.closed?
-    # 终结器只持有所属文件；借用回调可能捕获会话，不能让它经资源对象成为 GC 根。
-    @resources.owned_log = owned ? target : nil
-    @log_output = target
-    @log_redactor = nil
-    target
-  rescue Exception # rubocop:disable Lint/RescueException -- 替换失败时仍释放刚打开的文件。
-    target.close if owned && target && !target.closed?
-    raise
-  end
 end

data/lib/expect/matcher.rb

@@ -1,36 +1,40 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 驱动一次单会话或多会话匹配，管理模式优先级、EOF 和共享期限，不接管 IO 所有权。
   # 调度只在扫描、回调和 IO 操作之间检查期限，不强行中断用户代码或单次正则计算。
+  # @api private
   class Matcher
     # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
-    def initialize(patterns, timeout, deadline: nil)
-      @patterns = patterns
+    def initialize(patterns, timeout, deadline: nil, consume: true, reset_timeout_on_read: false)
+      @patterns = patterns.finalize!
       @sessions = patterns.sessions
+      @groups = patterns.groups
+      @consume = consume
+      @reset_timeout_on_read = reset_timeout_on_read
       @timeout = Expect.duration(timeout)
       # 相对期限可因接收或 continue 重算，总期限始终固定；两者共用单调时钟。
       @hard_deadline = deadline
       @deadline = next_deadline
-      @handled_eof = []
-      @stalled_matches = {}
+      @handled_eof = {}.compare_by_identity
+      @stalled_matches = {}.compare_by_identity
       @polled = false
       @expired_eof_continuation = false
     end
 
     # 运行匹配状态机；内部 :retry 表示继续循环，最终返回一个 Result。
     def run
-      @relay_buffers = {}
+      @relay_buffers = {}.compare_by_identity
       @sessions.each do |session|
-        buffer = session.__send__(:interaction_buffer)
+        buffer = session.interaction_buffer
         if buffer
           # 转义回调中的显式匹配临时接管读取，先消费转接已经预读的尾部。
           @relay_buffers[session] = buffer
-          session.__send__(:interaction_buffer=, nil)
-          session.__send__(:restore_relay_buffer, buffer)
+          session.interaction_buffer = nil
+          session.restore_relay_buffer(buffer)
           buffer.clear
         end
-        session.__send__(:reset_result)
+        session.reset_result
       end
       loop do
         # 先消费已缓冲的匹配，再处理 EOF，最后读取；避免进程退出时丢失最后一个匹配。
@@ -49,7 +53,7 @@ class Expect
       # 嵌套 expect 即使异常退出，也要把未消费尾部还给原 Relay 的同一个缓冲对象。
       @relay_buffers.each do |session, buffer|
         buffer.replace(session.clear_buffer)
-        session.__send__(:interaction_buffer=, buffer)
+        session.interaction_buffer = buffer
       end
     end
 
@@ -59,13 +63,13 @@ class Expect
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 声明优先级与单轮快照须在同一次扫描保持一致。
     def find_match
       # 单组且来源不重复时无需缓存；重复来源才为本轮扫描建立快照表。
-      groups = @patterns.groups
+      groups = @groups
       if groups.size > 1 || (groups.first && groups.first.first.size > @sessions.size)
         snapshots = {}.compare_by_identity
       end
       groups.each do |sessions, patterns|
         sessions.each do |session|
-          next if @handled_eof.include?(session)
+          next if @handled_eof.key?(session)
 
           buffer = snapshots ? (snapshots[session] ||= session.buffer) : session.buffer
           stalled = @stalled_matches[session]
@@ -99,23 +103,22 @@ class Expect
       @literal_misses ||= {}.compare_by_identity
       misses = (@literal_misses[session] ||= {}.compare_by_identity)
       previous = misses[pattern]
-      generation = session.__send__(:buffer_generation)
-      # 缓冲代次未变意味着只有尾部追加；模式对象的 value 被替换时也不能沿用旧扫描位置。
-      offset = if previous && previous[0] == generation && previous[2].equal?(pattern.value)
+      generation = session.buffer_generation
+      # 模式已冻结；缓冲代次未变意味着只有尾部追加。
+      offset = if previous && previous[0] == generation
                  return nil if previous[1] == buffer.bytesize
 
                  [previous[1] - pattern.value.bytesize + 1, 0].max
                else
                  0
                end
-      position = pattern.locate(buffer, offset: offset)
+      position = pattern.locate(buffer, offset:)
       if position
         misses.delete(pattern)
       else
         entry = (misses[pattern] ||= [])
         entry[0] = generation
         entry[1] = buffer.bytesize
-        entry[2] = pattern.value
       end
       position
     end
@@ -123,7 +126,7 @@ class Expect
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
     def handle_match(session, pattern, position)
       previous_buffer = session.buffer
-      result = session.__send__(:record_match, pattern, position)
+      result = session.record_match(pattern, position, consume: @consume)
       action = pattern.call(session)
       return result unless continuing?(action)
 
@@ -132,30 +135,31 @@ class Expect
         stalled = (@stalled_matches[session] ||= { buffer: previous_buffer, patterns: [] })
         stalled[:patterns] << pattern
       end
-      @deadline = next_deadline if action == CONTINUE
+      @deadline = next_deadline if CONTINUE.equal?(action)
       # 总期限到达时回主循环先派发已知 EOF；仅相对期限延续原有立即超时语义。
-      return handle_timeout if action == CONTINUE_WITHOUT_RESET && expired? && !hard_expired?
+      return handle_timeout if CONTINUE_WITHOUT_RESET.equal?(action) && expired? && !hard_expired?
 
       :retry
     end
 
     # 找出尚未派发 EOF 事件的会话，保证每个源只处理一次结束事件。
     def unhandled_eof
-      @sessions.find { |session| session.eof? && !@handled_eof.include?(session) }
+      @sessions.find { |session| session.eof? && !@handled_eof.key?(session) }
     end
 
     # 将剩余字节交给 EOF 回调；需要继续时等待其他源，全部结束则立即返回。
     def handle_eof(session)
-      result = session.__send__(:record_eof)
-      @handled_eof << session
+      result = session.record_eof
+      @handled_eof[session] = true
       actions = @patterns.eof_patterns_for(session).map { |pattern| pattern.call(session) }
       return result unless actions.any? { |action| continuing?(action) }
 
-      @deadline = next_deadline if actions.include?(CONTINUE)
-      return result if @sessions.all? { |candidate| @handled_eof.include?(candidate) }
+      reset_timeout = actions.any? { |action| CONTINUE.equal?(action) }
+      @deadline = next_deadline if reset_timeout
+      return result if @handled_eof.size == @sessions.size
 
       # 期限已过时不再扫描文本，但先派发已知 EOF；最后一个源结束不能被误报为超时。
-      @expired_eof_continuation = !actions.include?(CONTINUE) && expired?
+      @expired_eof_continuation = !reset_timeout && expired?
 
       :retry
     end
@@ -192,23 +196,23 @@ class Expect
         session = by_io ? by_io.fetch(io) : sessions.find { |candidate| candidate.to_io.equal?(io) }
         begin
           # 转接回调消费匹配内容，余下字节交回 Relay，不能在这里提前转发两次。
-          data = session.__send__(:read_available, propagate: !@relay_buffers.key?(session))
+          data = session.read_available(propagate: !@relay_buffers.key?(session))
         rescue Errno::EINTR
           next
         rescue IOError, SystemCallError => error
-          return session.__send__(:record_error, error)
+          return session.record_error(error)
         end
         @stalled_matches.delete(session) if data
-        @deadline = next_deadline if data && session.reset_timeout_on_read?
+        @deadline = next_deadline if data && @reset_timeout_on_read
       end
       :retry
     end
 
     # 返回本次仍需监听的会话，供读取选择和超时回调使用。
-    def active_sessions = @sessions.reject { |session| @handled_eof.include?(session) }
+    def active_sessions = @sessions.reject { |session| @handled_eof.key?(session) }
 
     # 只有约定的继续符号会驱动下一轮，普通回调返回值不会改变等待流程。
-    def continuing?(action) = [CONTINUE, CONTINUE_WITHOUT_RESET].include?(action)
+    def continuing?(action) = CONTINUE.equal?(action) || CONTINUE_WITHOUT_RESET.equal?(action)
 
     # 使用单调时钟计算期限；nil 一直表示无限等待，不受系统时间调整影响。
     # 每次重置都重新与总期限取较早者，避免连续输入或继续回调无限推迟结束。
@@ -224,22 +228,22 @@ class Expect
     def remaining = @deadline && [@deadline - Expect.monotonic, 0].max
 
     # 判断有限期限是否已到达；无限等待不会触发超时。
-    def expired? = @deadline && Expect.monotonic >= @deadline
+    def expired? = !@deadline.nil? && Expect.monotonic >= @deadline
 
     # 绝对总期限不受接收数据和 continue 重置；已知 EOF 仍按原顺序派发。
-    def hard_expired? = @hard_deadline && Expect.monotonic >= @hard_deadline
+    def hard_expired? = !@hard_deadline.nil? && Expect.monotonic >= @hard_deadline
 
-    # select 失败时无法归属单个源，为本次会话记录同一原始异常并返回首个结果。
+    # select 失败时无法归属单个源，只更新仍监听的会话；已派发 EOF 的结果保持不变。
     def record_error(error)
-      @sessions.map { |session| session.__send__(:record_error, error) }.first
+      active_sessions.map { |session| session.record_error(error) }.first
     end
 
     # 为活跃会话记录超时，回调接收全部活跃源；只有重置计时的继续符号能重新等待。
     # 已到总期限仍通知超时回调，但不接受继续请求，且不消费尚未匹配的字节。
     def handle_timeout
-      results = active_sessions.map { |session| session.__send__(:record_error, :timeout) }
+      results = active_sessions.map { |session| session.record_error(:timeout) }
       action = @patterns.timeout_pattern&.call(active_sessions)
-      return results.first unless action == CONTINUE && !hard_expired?
+      return results.first unless CONTINUE.equal?(action) && !hard_expired?
 
       @deadline = next_deadline
       @polled = false

data/lib/expect/pattern.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
-class Expect
+module Expect
   # 一个已编号的文本模式或事件及其回调；匹配结果统一使用字节偏移，便于精确消费 IO 缓冲。
-  Pattern = Struct.new(:number, :value, :callback, keyword_init: true) do
+  # @api private
+  Pattern = Data.define(:number, :value, :callback) do
+    # 复制字符串模式；Regexp 和 callable 只引用，不取得外部对象的生命周期。
+    def initialize(value:, number: nil, callback: nil)
+      super(value: value.is_a?(String) ? value.b.freeze : value, number:, callback:)
+    end
+
     # 将匹配会话或超时会话数组交给回调；额外上下文由调用方闭包保存。
     def call(subject)
       callback&.call(subject)
@@ -28,7 +34,7 @@ class Expect
                end
         unless text.valid_encoding?
           # 不完整的尾字符可能改变锚点或前瞻结果，必须等字符收齐后再匹配。
-          validate_incomplete_suffix!(text, final: final)
+          validate_incomplete_suffix!(text, final:)
           return nil
         end
         found = value.match(text)
@@ -58,4 +64,5 @@ class Expect
       raise EncodingError, "received invalid #{text.encoding} data; use a binary regexp (/.../n) for binary streams"
     end
   end
+  private_constant :Pattern
 end