linefeed 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e42d833b1d76721fb8906bdc579c93f0b5ab46071d2f0168adb3ffdef69f39b
+  data.tar.gz: 5e63818116b3d40432460f2cb90b516f0617a6dbaa67556ce0b8b4637da80161
+SHA512:
+  metadata.gz: 6767fa2a9741565af3dc7e92fe96f474a58d4aa250f8db67ab1b619c886fce099f0565b9c87a29d9cb9bbffd78ac5a2ec569b6749be88b30d5f391ddaca751a3
+  data.tar.gz: a58bba06bd570e0225f130c757ea7993809791b8cedd51ccb4f9ab59b77c68d6c941cd0e1e00e3bafc9ea61f94207e7bfdbf266bc3295470e675a08c4ad0e4a3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+# Linefeed
+
+Linefeed turns a push-style byte stream, of any chunk size, into individually yielded lines.
+
+* https://github.com/inopinatus/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.
+
+## Install
+
+```console
+gem install linefeed
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "linefeed"
+```
+
+## Protocol
+
+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.
+
+- `#close` marks end-of-incoming-data; if any data persists in the buffer, this yields a
+final unterminated string to the same handler.
+
+These method names are intentionally IO-ish so that you can mingle regular output files
+& IO streams with `linefeed` objects.
+
+## Usage
+
+```ruby
+require "linefeed"
+
+class Collector
+  include Linefeed
+
+  def initialize
+    @lines = []
+    linefeed { |line| @lines << line }
+  end
+end
+
+collector = Collector.new
+collector << "hello\nwor"
+collector << "ld\n"
+collector.close
+
+# @lines => ["hello\n", "world\n"]
+```
+
+Write custom `#<<` and `#close` handlers by passing blocks to `super` blocks:
+
+```ruby
+def <<(chunk)
+  super(chunk) do |line|
+    puts escape(line)
+  end
+end
+
+def close
+  super do |line|
+    puts escape(line) + "\n"
+  end
+  puts " -- all done."
+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.
+
+## License
+
+MIT. Copyright (c) 2025 inopinatus.
+
+## Contributing
+
+At https://github.com/inopinatus/linefeed.

data/examples/01_logger.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+require_relative 'demo'
+
+# Simplest possible example
+module Demo
+  class Logger
+    include Linefeed
+
+    def initialize(output)
+      line_no = 0
+      linefeed do |line|
+        output << "%.3d => %s" % [line_no += 1, line]
+      end
+    end
+  end
+end

data/examples/02_canonicalize.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+require_relative 'demo'
+
+# Per-line processing with headers & trailers
+module Demo
+  class Canonicalize < Consumer
+    def initialize(*)
+      super
+      @output << "---------- START\r\n"
+      @output << "Canonicalized: yes\r\n"
+      @output << "\r\n"
+    end
+
+    def process_line(line)
+      canonicalize(line)
+    end
+
+    def canonicalize(line)
+      line.chomp.sub(/[ \t]+$/, "") + "\r\n"
+    end
+
+    def close
+      super
+      @output << "---------- END\r\n"
+      @output.close
+    end
+  end
+end

data/examples/03_escaped.rb

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

data/examples/04_line_digest.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require_relative 'demo'
+require "digest"
+
+# Only outputs at close
+module Demo
+  class LineDigest
+    include Linefeed
+
+    def initialize(output)
+      @output = output
+      @line_digest = Digest("SHA256").new
+
+      linefeed do |line|
+        @line_digest.update(line)
+      end
+    end
+
+    def close
+      super
+      @output << @line_digest.hexdigest
+    end
+  end
+end

data/examples/05_chunk_digest.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require_relative 'demo'
+require "digest"
+
+# Not actually using Linefeed, but speaking the same protocol,
+# consuming entire chunks.
+#
+# Should give the same digest as LineDigest.
+module Demo
+  class ChunkDigest
+    def initialize(output)
+      @output = output
+      @digest = Digest("SHA256").new
+    end
+
+    def <<(chunk)
+      @digest << chunk
+    end
+
+    def close
+      @output << @digest.hexdigest
+    end
+  end
+end

data/examples/06_canonicalized_digest.rb

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

data/examples/07_null.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require_relative 'demo'
+
+# Intentionally fails to setup the feed and suffers for it.
+# Don't do this.
+module Demo
+  class Null
+    include Linefeed
+
+    def initialize(output)
+      @output = output
+      @count = 0
+    end
+
+    def <<(*)
+      super
+    rescue ArgumentError
+      @count += 1
+    end
+
+    def close
+      super
+    rescue ArgumentError
+      @output << "rescued #{@count += 1} time(s)"
+    end
+  end
+end

data/examples/consumer.rb

@@ -0,0 +1,16 @@
+# 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/examples/demo.rb

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

data/examples/demo_helper.rb

@@ -0,0 +1,31 @@
+# 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 close()=puts "#{@prefix} closed."
+  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
+    end
+
+    def register(klass)
+      @example_classes << klass
+    end
+
+    def setup_examples
+      @example_classes.map { |k| k.new(Output.new(k)) }
+    end
+  end
+end
+

data/lib/linefeed/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Linefeed
+  VERSION = "0.2.0"
+end

data/lib/linefeed.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "linefeed/version"
+
+module Linefeed
+  class Error < StandardError; end
+
+  def linefeed(&default_proc)
+    @__linefeed_default = default_proc
+    __linefeed_reset
+    self
+  end
+
+  def __linefeed_reset
+    @__linefeed_buffer = +"".b
+    @__linefeed_closed = false
+    self
+  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
+
+    @__linefeed_buffer ||= +"".b
+    @__linefeed_buffer << chunk
+
+    while (eol = @__linefeed_buffer.index("\n"))
+      per_line.call(@__linefeed_buffer.slice!(0..eol)) # includes the "\n"
+    end
+
+    self
+  end
+
+  # 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
+    self
+  end
+end

data/test/test_linefeed.rb

@@ -0,0 +1,95 @@
+# 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

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: linefeed
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+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'
+description: Linefeed turns a push-style byte stream, of any chunk size, into individually
+  yielded lines.
+email: inopinatus@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/01_logger.rb
+- examples/02_canonicalize.rb
+- examples/03_escaped.rb
+- examples/04_line_digest.rb
+- 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/version.rb
+- test/test_linefeed.rb
+homepage: https://github.com/inopinatus/linefeed
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/inopinatus/linefeed
+  source_code_uri: https://github.com/inopinatus/linefeed
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Yield lines from arbitrarily chunked byte streams
+test_files: []