io-like 0.3.1 → 0.4.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca93e63077fc81e1bf0bd7d8427525abf8b596f688b6e77c74435c97b0ee2b9e
+  data.tar.gz: 7a6db01e11f4c3801f55b6979cd20a996f4de0bd48d23e4712411c011bd8f64a
+SHA512:
+  metadata.gz: 5953bc03797b4ed77f36471422a218c31fc3c974433e4fd73c22447f8febcda78be50bb7008b10521020ddea7a28c46fc18fa4633face34700ecb667dd0dda05
+  data.tar.gz: fbc480607dd5bb87c6c3697ea72df10af4c4fc3a5c2b1c6f6353f4a39b7f04e8d62ed5847c7dadd4a4dede2d6c1e0e0a39bbc77b599db171d7a6c2d1985bb013

data/LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2020 Jeremy Bopp
+Copyright (c) 2024 Jeremy Bopp
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/NEWS.md

@@ -3,7 +3,20 @@
 This file lists noteworthy changes which may affect users of this project.  More
 detailed information is available in the rest of the documentation.
 
-<b>NOTE:</b> Date stamps in the following entries are in YYYY/MM/DD format.
+**NOTE:** Date stamps in the following entries are in YYYY/MM/DD format.
+
+
+## v0.4.0.pre1 (2025/05/07)
+* Reimplemented all version specific IO::Like modules as a single class
+  * **WARNING:** Breaks API compatibility with prior versions
+* Dropped support for Ruby less than 2.7
+* Added full API compatibility for Ruby 2.7 through 3.4
+  * Support for character encodings
+  * Asynchronous/nonblocking methods
+  * Many missing helper methods
+* Reworked spec handling to make it easier to import rubyspec snapshots almost
+  trivially (Grant Gardner, Jeremy Bopp)
+* Added code coverage tooling
 
 
 ## v0.3.1 (2020/02/09)

data/README.md

@@ -1,7 +1,6 @@
 # IO::Like - in the Likeness of IO
 
-A module which provides the functionality of an IO object to any including class
-which provides a couple of simple methods.
+A composable implementation of IO methods.
 
 ## LINKS
 
@@ -11,27 +10,19 @@ which provides a couple of simple methods.
 
 ## DESCRIPTION
 
-The IO::Like module provides all of the methods of typical IO implementations
-such as File; most importantly the read, write, and seek series of methods.  A
-class which includes IO::Like needs to provide only a few methods in order to
-enable the higher level methods.  Buffering is automatically provided by default
-for the methods which normally provide it in IO.
+This gem makes it possible to build filters or pipelines for processing data
+into or out of streams of bytes while maintaining compatibility with native Ruby
+IO classes.  Ruby IO classes may function as both sources and sinks, or entirely
+new IO implementations may be created.
 
 ## FEATURES
 
-* All standard Ruby 1.8.6 IO operations.
-* Buffered operations.
-* Configurable buffer size.
+* All standard Ruby 2.7 to 3.4 IO methods
+* Primitive IO interfaces to facilitate creating IO filters/pipelines
 
 ## KNOWN BUGS/LIMITATIONS
 
-* Only up to version 1.8.6 of Ruby's IO interface is implemented.
-* Ruby's finalization capabilities fall a bit short in a few respects, and as a
-  result, it is impossible to cause the close, close_read, or close_write
-  methods to be called automatically when an including class is garbage
-  collected.  Define a class open method in the manner of File.open which
-  guarantees that an appropriate close method will be called after executing a
-  block.  Other than that, be diligent about calling the close methods.
+* None at this time
 
 ## SYNOPSIS
 
@@ -42,96 +33,96 @@ A simple ROT13 codec:
 
 ```ruby
 require 'io/like'
+require 'io/like_helpers/delegated_io'
+require 'io/like_helpers/io_wrapper'
 
-class ROT13Filter
-  include IO::Like
+include IO::LikeHelpers
 
-  def self.open(delegate_io)
-    filter = new(delegate_io)
-    return filter unless block_given?
+class ROT13IO < IO::Like
+  def initialize(delegate, autoclose: true, **kwargs)
+    delegate = delegate.rot13_filter if self.class === delegate
+    @rot13_filter = ROT13Filter.new(delegate, autoclose: autoclose)
 
-    begin
-      yield(filter)
-    ensure
-      filter.close unless filter.closed?
-    end
+    super(@rot13_filter, autoclose: true, **kwargs)
   end
 
-  def initialize(delegate_io)
-    @delegate_io = delegate_io
-  end
+  protected
 
-  private
-
-  def encode_rot13(string)
-    result = string.dup
-    0.upto(result.length) do |i|
-      case result[i]
-      when 65..90
-        result[i] = (result[i] - 52) % 26 + 65
-      when 97..122
-        result[i] = (result[i] - 84) % 26 + 97
-      end
-    end
-    result
+  def rot13_filter
+    flush if writable?
+    @rot13_filter
   end
+end
 
-  def unbuffered_read(length)
-    encode_rot13(@delegate_io.sysread(length))
-  end
+class ROT13Filter < DelegatedIO
+  def initialize(delegate, autoclose: true, **kwargs)
+    if IO === delegate
+      delegate = IOWrapper.new(delegate, autoclose: autoclose)
+      autoclose = true
+    end
 
-  def unbuffered_seek(offset, whence = IO::SEEK_SET)
-    @delegate_io.sysseek(offset, whence)
+    super(delegate, autoclose: autoclose, **kwargs)
   end
 
-  def unbuffered_write(string)
-    @delegate_io.syswrite(encode_rot13(string))
+  def read(length, buffer: nil, buffer_offset: 0)
+    result = super
+    if buffer.nil?
+      encode_rot13(result)
+    else
+      encode_rot13(buffer, buffer_offset: buffer_offset)
+    end
+    result
   end
-end
-
-File.open('normal_file.txt', 'w') do |f|
-  f.puts('This is a test')
-end
 
-File.open('rot13_file.txt', 'w') do |f|
-  ROT13Filter.open(f) do |rot13|
-    rot13.puts('This is a test')
+  def write(buffer, length: buffer.bytesize)
+    super(encode_rot13(buffer[0, length]), length: length)
   end
-end
 
-File.open('normal_file.txt') do |f|
-  ROT13Filter.open(f) do |rot13|
-    puts(rot13.read)                      # -> Guvf vf n grfg
-  end
-end
+  private
 
-File.open('rot13_file.txt') do |f|
-  ROT13Filter.open(f) do |rot13|
-    puts(rot13.read)                      # -> This is a test
+  def encode_rot13(buffer, buffer_offset: 0)
+    buffer_offset.upto(buffer.length - 1) do |i|
+      ord = buffer[i].ord
+      case ord
+      when 65..90
+        buffer[i] = ((ord - 52) % 26 + 65).chr
+      when 97..122
+        buffer[i] = ((ord - 84) % 26 + 97).chr
+      end
+    end
+    buffer
   end
 end
 
-File.open('normal_file.txt') do |f|
-  ROT13Filter.open(f) do |rot13|
-    rot13.pos = 5
-    puts(rot13.read)                      # -> vf n grfg
+if $0 == __FILE__
+  # Write encoded content to stdout, leaving stdout open after completion.
+  ROT13IO.open(STDOUT, autoclose: false) do |rot13|
+    rot13.puts('This is a test. 1234!')   # -> Guvf vf n grfg. 1234!
   end
-end
 
-File.open('rot13_file.txt') do |f|
-  ROT13Filter.open(f) do |rot13|
-    rot13.pos = 5
-    puts(rot13.read)                      # -> is a test
+  # Decode content from an input stream and read as lines.
+  IO.pipe do |r, w|
+    w.puts('This is a test. 1234!')
+    w.puts('Guvf vf n grfg. 4567!')
+    w.close
+    ROT13IO.open(r) do |rot13|
+      puts(rot13.each_line.to_a.inspect)  # -> ["Guvf vf n grfg. 1234!\n", "This is a test. 4567!\n"]
+    end
   end
-end
 
-File.open('normal_file.txt') do |f|
-  ROT13Filter.open(f) do |rot13|
-    ROT13Filter.open(rot13) do |rot26|    # ;-)
-      puts(rot26.read)                    # -> This is a test
+  # Double decode content (noop) and dump to stdout using IO.copy_stream.
+  IO.pipe do |r, w|
+    w.puts('This is a test. 1234!')
+    w.close
+    ROT13IO.open(r) do |rot13|
+      ROT13IO.open(rot13) do |rot26|
+        IO.copy_stream(rot26, STDOUT)     # -> This is a test. 1234!
+      end
     end
   end
 end
+
+# vim: ts=2 sw=2 et
 ```
 
 ## REQUIREMENTS
@@ -140,18 +131,8 @@ end
 
 ## INSTALL
 
-Download the GEM file and install it with:
-
-    $ gem install io-like-VERSION.gem
-
-or directly with:
-
     $ gem install io-like
 
-Removal is the same in either case:
-
-    $ gem uninstall io-like
-
 ## DEVELOPERS
 
 After checking out the source, run:
@@ -216,7 +197,7 @@ be more easily accepted if they are consistent with the rest of the code.
 ```
 (The MIT License)
 
-Copyright (c) 2020 Jeremy Bopp
+Copyright (c) 2024 Jeremy Bopp
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -240,8 +221,8 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ## RUBYSPEC LICENSE
 
-Files under the `rubyspec` directory are copied whole or in part from the
-Rubyspec project.
+Files under the `rubyspec` directory are copied in whole from the Rubyspec
+project.
 
 ```
 Copyright (c) 2008 Engine Yard, Inc. All rights reserved.