linefeed 0.3.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acb4d8a8b79c2913d1a9b3118f11c5fc61b1bd956cecfb3c921a8a34282f369c
-  data.tar.gz: 7d3174f86ebe7c3af2960b425b8c656427eb181158c87c347db16c896fda4cef
+  metadata.gz: a7ee8b08d068e093abefa6cefe66b22278a0fee127b393d17944d5c96893966a
+  data.tar.gz: 9a5d006b788929240e54c48c5134779fed09d16fdcb88cf2d89b9442a3b7173c
 SHA512:
-  metadata.gz: d702bc5d2e3b49141abefd70dd72b4d84d5fbac82892cf88f97ad1da11e4fbf65af0db7dc996a198f9b8674bfdba2be456cdcfaba76058a3db45e31e8bf4cc2d
-  data.tar.gz: e94154e6ae96d1b8abe5dfff8f39653ded9b7dbd10bbe1e771f4baeb1805789b773e1a9b6506a2081bf0195704b68971604e86723d2d2654c2e259723c642c48
+  metadata.gz: 72c10dbecaf129be413c7db8abf471cf4f5ae9cf5f2936a89e67385f3631adbd0d6e4482eb8a54b0abc8c43d7b05f07bf0f1cfa78df1110b1a1f2c2e1fecd27b
+  data.tar.gz: 6aa585d5375f2aac5f2a3565822ff82d091ed4cc07c1605525b795739f02e1bb09f427d33346c147d3af6b8dd2c7206eee7459807517603d0af0c1947154fc87

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.2 - 2026-01-04
+- fix example 6 when run standalone
+
+## 1.0.1 - 2026-01-04
+- style nits
+
+## 1.0.0 - 2026-01-04
+- faster again
+- better errors
+- ci & doco
+
+## 0.3.0 - 2026-01-03
+- speedup
+- safety rails
+
+## 0.2.0 - 2026-01-03
+- gemify
+
+## 0.1.0 - 2025-12-31
+- idea

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 inopinatus
+Copyright (c) 2026 inopinatus
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,14 +1,14 @@
 # Linefeed
 
-Linefeed turns a push-style byte stream, of any chunk size, into individually yielded lines.
+Linefeed turns a chunked byte stream into individually yielded lines.
 
 * https://github.com/inopinatus/linefeed
+* https://inopinatus.github.io/linefeed/
 
 ## Why?
 
-When you're downstream of the read on a binary-mode chunked stream and can't easily turn that into a nice efficient `IO#readlines`.
-
-Also, it has nice properties if you chain them together.
+When you're downstream of the read on a binary-mode chunked stream and want a push-style
+take on `#each_line` that doesn't burn too much memory.
 
 ## Install
 
@@ -24,12 +24,12 @@ gem "linefeed"
 
 ## Protocol
 
-Including `linefeed` supplies two methods, `#<<` and `#close`.  The idea is for external
+Including `Linefeed` supplies two methods, `#<<` and `#close`.  The idea is for external
 producers to drive processing by calls to these methods.
 
 - `#<<` accepts an arbitrary-size chunk of incoming data and yields each LF-terminated line
-to a handler set by `linefeed { |line| ... }` as an 8-bit ASCII string.  Lines yielded
-will include the trailing LF.
+to a handler set by `linefeed { |line| ... }`.  Lines yielded will be 8-bit ASCII strings
+and include the trailing LF.
 
 - `#close` marks end-of-incoming-data; if any data persists in the buffer, this yields a
 final unterminated string to the same handler.
@@ -76,18 +76,12 @@ def close
 end
 ```
 
-See `examples/` for more, like daisy-chaining, or updating a digest.
-
-## Examples
-
-Run `examples/demo.rb` and review the numbered examples it includes.
-
-If testing with cooked interactive input at the console, note that `linefeed`'s examples necessarily read in binary mode, so ^D may not be instant EOF.
+See Examples for more, like daisy-chaining, or updating a digest.
 
 ## License
 
-MIT. Copyright (c) 2025 inopinatus.
+MIT license. Copyright (c) 2026 inopinatus
 
 ## Contributing
 
-At https://github.com/inopinatus/linefeed.
+Visit https://github.com/inopinatus/linefeed to open a PR.

data/examples/01_logger.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+
 require_relative 'demo'
+require 'linefeed'
 
 # Simplest possible example
 module Demo
@@ -9,7 +11,8 @@ module Demo
     def initialize(output)
       line_no = 0
       linefeed do |line|
-        output << "%.3d => %s" % [line_no += 1, line]
+        line_no += 1
+        output << format('%<line_no>03d => %<line>s', line_no: line_no, line: line)
       end
     end
   end

data/examples/02_canonicalize.rb

@@ -1,14 +1,22 @@
 # frozen_string_literal: true
+
 require_relative 'demo'
+require 'linefeed'
 
 # Per-line processing with headers & trailers
 module Demo
-  class Canonicalize < Consumer
-    def initialize(*)
-      super
+  class Canonicalize
+    include Linefeed
+
+    def initialize(output)
+      @output = output
       @output << "---------- START\r\n"
       @output << "Canonicalized: yes\r\n"
       @output << "\r\n"
+
+      linefeed do |line|
+        output << process_line(line)
+      end
     end
 
     def process_line(line)
@@ -16,7 +24,7 @@ module Demo
     end
 
     def canonicalize(line)
-      line.chomp.sub(/[ \t]+$/, "") + "\r\n"
+      "#{line.chomp.sub(/[ \t]+$/, '')}\r\n"
     end
 
     def close
@@ -25,4 +33,4 @@ module Demo
       @output.close
     end
   end
-end
+end

data/examples/03_escaped.rb

@@ -1,23 +1,31 @@
 # frozen_string_literal: true
+
 require_relative 'demo'
+require 'linefeed'
 
 # Handling the protocol via super
 module Demo
-  class Escaped < Consumer
+  class Escaped
+    include Linefeed
+
+    def initialize(output)
+      @output = output
+    end
+
     def escape(line)
-      line.sub(/^(-|From )/, "- \\1")
+      line.sub(/^(-|From )/, '- \\1')
     end
 
     def <<(chunk)
-      super(chunk) do |line|
+      super do |line|
         @output << escape(line)
       end
     end
 
     def close
       super do |line|
-        @output << escape(line) + "\n"
+        @output << "#{escape(line)}\n"
       end
     end
   end
-end
+end

data/examples/04_line_digest.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
+
 require_relative 'demo'
-require "digest"
+require 'linefeed'
+require 'digest'
 
 # Only outputs at close
 module Demo
@@ -9,7 +11,7 @@ module Demo
 
     def initialize(output)
       @output = output
-      @line_digest = Digest("SHA256").new
+      @line_digest = Digest('SHA256').new
 
       linefeed do |line|
         @line_digest.update(line)

data/examples/05_chunk_digest.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
+
 require_relative 'demo'
-require "digest"
+require 'linefeed'
+require 'digest'
 
 # Not actually using Linefeed, but speaking the same protocol,
 # consuming entire chunks.
@@ -10,7 +12,7 @@ module Demo
   class ChunkDigest
     def initialize(output)
       @output = output
-      @digest = Digest("SHA256").new
+      @digest = Digest('SHA256').new
     end
 
     def <<(chunk)

data/examples/06_canonicalized_digest.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
-require_relative 'demo'
-require "delegate"
+
+require_relative '02_canonicalize'
+require_relative '04_line_digest'
+require 'delegate'
 
 # Easy chaining
 module Demo
-  class CanonicalizedDigest < DelegateClass(Consumer)
+  class CanonicalizedDigest < DelegateClass(Canonicalize)
     def initialize(output)
       super(Canonicalize.new(LineDigest.new(output)))
     end

data/examples/07_null.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+
 require_relative 'demo'
+require 'linefeed'
 
 # Intentionally fails to setup the feed and suffers for it.
 # Don't do this.

data/examples/demo.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
-require_relative "../lib/linefeed"
-require_relative "demo_helper"
+
+require_relative 'demo_helper'
 
 if $0 == __FILE__
-  example_files = Dir[File.join(__dir__, "[0-9][0-9]_*.rb")].sort
+  example_files = Dir[File.join(__dir__, '[0-9][0-9]_*.rb')]
   example_files.each do |path|
     require_relative File.basename(path)
   end
@@ -11,10 +11,11 @@ end
 
 def run
   recipients = Demo.setup_examples
+  input = Demo.input_pipe(ARGF)
   maxlen = 8192
-  chunk = "".b
+  chunk = ''.b
 
-  while $stdin.read(maxlen, chunk)
+  while input.read(maxlen, chunk) && !chunk.empty?
     recipients.each do |r|
       r << chunk
     end
@@ -22,4 +23,5 @@ def run
   recipients.each(&:close)
 end
 
-at_exit { run } unless @at_exit_installed; @at_exit_installed = true
+at_exit { run unless $! } unless @at_exit_installed
+@at_exit_installed = true

data/examples/demo_helper.rb

@@ -1,22 +1,34 @@
 # frozen_string_literal: true
-require_relative 'consumer'
 
 module Demo
   # IO trap
   class Output
     def initialize(klass)=@prefix = klass.to_s
-    def <<(o)=puts "#{@prefix}: #{o.inspect}"
+    def <<(obj)=puts "#{@prefix}: #{obj.inspect}"
     def close()=puts "#{@prefix} closed."
   end
 
+  # decouple from tty if demo run interactively
+  def self.input_pipe(source)
+    return source unless $stdin.tty?
+
+    reader, writer = IO.pipe
+    Thread.new do
+      IO.copy_stream(source, writer)
+    ensure
+      writer.close unless writer.closed?
+    end
+    reader
+  end
+
   # Example registry
   @example_classes = []
   class << self
     def const_added(const_name)
       super
-      if const_get(const_name, false) in Class => klass
-        register(klass)
-      end
+      return unless const_get(const_name, false) in Class => klass
+
+      register(klass)
     end
 
     def register(klass)
@@ -28,4 +40,3 @@ module Demo
     end
   end
 end
-

data/lib/linefeed/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Linefeed
+  # Base error for linefeed-specific failures.
+  class Error < StandardError; end
+
+  # Raised when linefeed is started more than once.
+  class StartError < Error; end
+
+  # Raised when operations are attempted after close.
+  class ClosedError < Error
+    def initialize(message = 'already closed')
+      super
+    end
+  end
+
+  # Raised when no handler is provided for line processing. Subclass of
+  # {ArgumentError}[https://docs.ruby-lang.org/en/master/ArgumentError.html]
+  class MissingHandler < ArgumentError; end
+end

data/lib/linefeed/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Linefeed
-  VERSION = "0.3.0"
+  VERSION = '1.0.2'
 end

data/lib/linefeed.rb

@@ -1,51 +1,130 @@
 # frozen_string_literal: true
 
-require "linefeed/version"
+require 'linefeed/version'
+require 'linefeed/errors'
+
+# Include Linefeed to enable handling of chunked binary streams as yielded
+# lines.
+#
+# See README for more.
 
 module Linefeed
-  class Error < StandardError; end
+  # Set up linefeed processing and install a default handler.
+  #
+  # call-seq:
+  #   linefeed { |line| ... } -> self
+  #
+  # The handler receives each LF-terminated line as a binary +String+ and will
+  # be invoked on #<< and #close unless a per-call block is provided.  A final
+  # unterminated line may be yielded by #close.
+  #
+  # Raises MissingHandler if no block is given.<br>
+  # Raises StartError if linefeed was already started.<br>
+  # Raises ClosedError if linefeed was already closed.
+  def linefeed(&)
+    raise MissingHandler unless block_given?
 
-  def linefeed(&default_proc)
-    raise ArgumentError, "linefeed already called" if @__linefeed_called
-    @__linefeed_default = default_proc
-    @__linefeed_buffer = +"".b
-    @__linefeed_closed = false
-    @__linefeed_called = true
-    self
+    linefeed_start(&)
   end
 
-  # Called by push-type source to write to us.
-  def <<(chunk, &per_line)
-    per_line ||= @__linefeed_default
-    raise Error, "already closed" if @__linefeed_closed
-    raise ArgumentError, "no line handler" unless per_line
+  # Push a binary chunk to the receiver.
+  #
+  # call-seq:
+  #   self << chunk -> self
+  #   self << chunk { |line| ... } -> self
+  #
+  # The receiver yields complete LF-terminated lines to the handler.
+  # Any # trailing partial line is buffered until the next chunk or #close.
+  # Lines will be 8-bit ASCII +String+ values and always include the trailing +\n+.
+  #
+  # If you override this method, call +super+ with the chunk and pass a block
+  # to receive each line:
+  #
+  #   def <<(chunk)
+  #     super(chunk) { |line| puts escape(line) }
+  #   end
+  #
+  # Raises MissingHandler if no handler is given and no default handler was installed.<br>
+  # Raises ClosedError if called after #close.
+  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+  def <<(chunk, &handler)
+    handler ||= @__linefeed_handler
+    raise MissingHandler unless handler
+    raise ClosedError if @__linefeed_closed
 
-    @__linefeed_called = true
-    @__linefeed_buffer ||= +"".b
-    @__linefeed_buffer << chunk
+    linefeed_start unless @__linefeed_started
+    buf = @__linefeed_buffer
 
-    start = 0
-    while (eol = @__linefeed_buffer.index("\n", start))
-      per_line.call(@__linefeed_buffer.slice(start..eol)) # includes the "\n"
-      start = eol + 1
+    if chunk.getbyte(-1) == 10
+      if buf.empty?
+        chunk.each_line("\n", &handler)
+      else
+        buf << chunk
+        buf.each_line("\n", &handler)
+        buf.clear
+      end
+      return self
     end
 
-    if start > 0
-      @__linefeed_buffer = @__linefeed_buffer.byteslice(start, @__linefeed_buffer.bytesize - start) || +"".b
+    buf << chunk
+    return self if chunk.index("\n").nil?
+
+    buf.each_line("\n") do |line|
+      if line.getbyte(-1) == 10
+        handler.call(line)
+      else
+        @__linefeed_buffer = line
+      end
     end
 
     self
   end
+  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+  # Close the stream and flush any buffered data.
+  #
+  # call-seq:
+  #   close -> self
+  #   close { |line| ... } -> self
+  #
+  # If the buffer contains an unterminated line, it is yielded once to the
+  # handler as a binary +String+ without a trailing +\n+.
+
+  # It is valid to call #close without any prior calls to #<< or #linefeed.
+  #
+  # If you override this method, call +super+ and pass a block to receive the
+  # final partial line:
+  #
+  #   def close
+  #     super { |line| puts escape(line) }
+  #     puts "-- all done."
+  #   end
+  #
+  # Raises MissingHandler if no handler is given and no default handler was installed.<br>
+  # Raises ClosedError if called more than once.
+  def close(&handler)
+    handler ||= @__linefeed_handler
+    raise MissingHandler unless handler
+    raise ClosedError if @__linefeed_closed
 
-  # Called at end-of-stream.
-  def close(&per_line)
-    per_line ||= @__linefeed_default
-    raise Error, "already closed" if @__linefeed_closed
-    raise ArgumentError, "no line handler" unless per_line
     @__linefeed_closed = true
     return self if !@__linefeed_buffer || @__linefeed_buffer.empty?
 
-    per_line.call(@__linefeed_buffer.slice!(0, @__linefeed_buffer.bytesize)) # final unterminated line
+    handler.call(@__linefeed_buffer.dup)
+    @__linefeed_buffer.clear
+    self
+  end
+
+  private
+
+  def linefeed_start(&handler)
+    raise StartError, 'already started' if @__linefeed_started
+    raise ClosedError if @__linefeed_closed
+
+    @__linefeed_handler = handler
+    @__linefeed_buffer = +''.b
+    @__linefeed_closed = false
+    @__linefeed_started = true
     self
   end
 end

metadata

@@ -1,56 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: linefeed
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Joshua Goodall
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: irb
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+dependencies: []
 description: Linefeed turns a push-style byte stream, of any chunk size, into individually
   yielded lines.
 email: inopinatus@hey.com
@@ -58,6 +16,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - examples/01_logger.rb
@@ -67,18 +26,20 @@ files:
 - examples/05_chunk_digest.rb
 - examples/06_canonicalized_digest.rb
 - examples/07_null.rb
-- examples/consumer.rb
 - examples/demo.rb
 - examples/demo_helper.rb
 - lib/linefeed.rb
+- lib/linefeed/errors.rb
 - lib/linefeed/version.rb
-- test/test_linefeed.rb
-homepage: https://github.com/inopinatus/linefeed
+homepage: https://inopinatus.github.io/linefeed/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/inopinatus/linefeed
+  homepage_uri: https://inopinatus.github.io/linefeed/
   source_code_uri: https://github.com/inopinatus/linefeed
+  changelog_uri: https://github.com/inopinatus/linefeed/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/inopinatus/linefeed/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib

data/examples/consumer.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-# simple base for demos
-module Demo
-  class Consumer
-    include Linefeed
-
-    def initialize(output)
-      @output = output
-
-      linefeed do |line|
-        output << process_line(line)
-      end
-    end
-  end
-end

data/test/test_linefeed.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-require "minitest/autorun"
-require_relative "../lib/linefeed"
-
-class LinefeedTest < Minitest::Test
-  class StandardReceiver
-    include Linefeed
-    attr_reader :lines
-
-    def initialize
-      @lines = []
-      linefeed { |line| @lines << line }
-    end
-  end
-
-  class CustomReceiver
-    include Linefeed
-    attr_reader :lines
-
-    def initialize
-      @lines = []
-    end
-
-    def <<(chunk)
-      super do |line|
-        @lines << "line:#{line}"
-      end
-    end
-
-    def close
-      super do |line|
-        @lines << "eof:#{line}"
-      end
-    end
-  end
-
-  def test_basic_yield
-    receiver = StandardReceiver.new
-    receiver << "a\nb\n"
-
-    assert_equal ["a\n", "b\n"], receiver.lines
-  end
-
-  def test_works_across_chunks
-    receiver = StandardReceiver.new
-    receiver << "a"
-    receiver << "\n"
-    receiver << "b"
-    receiver << "\n"
-
-    assert_equal ["a\n", "b\n"], receiver.lines
-  end
-
-  def test_flush_unterminated
-    receiver = StandardReceiver.new
-    receiver << "tail"
-    receiver.close
-
-    assert_equal ["tail"], receiver.lines
-  end
-
-  def test_empty_close_does_nothing
-    receiver = StandardReceiver.new
-    receiver.close
-
-    assert_equal [], receiver.lines
-  end
-
-  def test_you_forget_the_handlers
-    obj = Object.new
-    obj.extend(Linefeed)
-
-    assert_raises(ArgumentError) { obj << "a\n" }
-    assert_raises(ArgumentError) { obj.close }
-  end
-
-  def test_raise_after_close
-    receiver = StandardReceiver.new
-    receiver.close
-
-    assert_raises(Linefeed::Error) { receiver << "a\n" }
-    assert_raises(Linefeed::Error) { receiver.close }
-  end
-
-  def test_custom_handlers
-    receiver = CustomReceiver.new
-
-    receiver << "a"
-    receiver << "\n"
-    receiver << "b"
-    receiver.close
-    assert_equal ["line:a\n", "eof:b"], receiver.lines
-  end
-end