io-like 0.3.0 → 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,57 +1,22 @@
-LICENSE text follows:
-
-  IO::Like is copyrighted free software by Jeremy Bopp
-  <jeremy at bopp dot net>.  You can redistribute it and/or modify it under
-  either the terms of the GPL (see the included GPL file), or the conditions
-  below:
-
-    1. You may make and give away verbatim copies of the source form of the
-       software without restriction, provided that you duplicate all of the
-       original copyright notices and associated disclaimers.
-
-    2. You may modify your copy of the software in any way, provided that
-       you do at least ONE of the following:
-
-         a) place your modifications in the Public Domain or otherwise
-            make them Freely Available, such as by posting said
-            modifications to Usenet or an equivalent medium, or by allowing
-            the author to include your modifications in the software.
-
-         b) use the modified software only within your corporation or
-            organization.
-
-         c) rename any non-standard executables so the names do not conflict
-            with standard executables, which must also be provided.
-
-         d) make other distribution arrangements with the author.
-
-    3. You may distribute the software in object code or executable
-       form, provided that you do at least ONE of the following:
-
-         a) distribute the executables and library files of the software,
-            together with instructions (in the manual page or equivalent)
-            on where to get the original distribution.
-
-         b) accompany the distribution with the machine-readable source of
-            the software.
-
-         c) give non-standard executables non-standard names, with
-            instructions on where to get the original software distribution.
-
-         d) make other distribution arrangements with the author.
-
-    4. You may modify and include the covered part of the software into any
-       other software (possibly commercial).  But some files in the
-       distribution may not be written by the author, such that they are not
-       under these terms.  (See the file LEGAL for a listing and conditions)
-
-    5. The scripts and library files supplied as input to or produced as
-       output from the software do not automatically fall under the
-       copyright of the software, but belong to whomever generated them,
-       and may be sold commercially, and may be aggregated with this
-       software.
-
-    6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
-       IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-       PURPOSE.
+(The MIT License)
+
+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
+'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/{NEWS → NEWS.md}

@@ -1,30 +1,48 @@
-= News and Notifications by Version
+# News and Notifications by Version
 
 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.3.0 (2009/04/29)
+## 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)
+
+* Removed the rubyforge reference from the gemspec (Jordan Pickwell)
+
+
+## v0.3.0 (2009/04/29)
 
 * Fixed the rewind method to work with write-only streams
 * Fixed the read, gets, and readline methods to return partial data if they have
   such data but receive low level errors before reaching a stopping point
 * Renamed all private methods so that it is highly unlikely that they will be
-  accidentally overridden.
+  accidentally overridden
 * Eliminated warnings caused by referencing uninitialized instance variables
 * Improved the documentation for the read, gets, and readline methods
 
 
-== v0.2.0 (2009/03/11)
+## v0.2.0 (2009/03/11)
 
 * Added mspec tests borrowed from the rubyspec project
 * Fixed many, many defects related to IO compatibility (Mostly obscure corner
   cases)
 
 
-== v0.1.0 (2008/07/03)
+## v0.1.0 (2008/07/03)
 
 * Initial release
 * All read, write, and seek functions implemented as defined in Ruby 1.8.6

data/README.md

@@ -0,0 +1,250 @@
+# IO::Like - in the Likeness of IO
+
+A composable implementation of IO methods.
+
+## LINKS
+
+* Homepage :: http://github.com/javanthropus/io-like
+* Documentation :: http://rdoc.info/gems/io-like/frames
+* Source :: http://github.com/javanthropus/io-like
+
+## DESCRIPTION
+
+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 2.7 to 3.4 IO methods
+* Primitive IO interfaces to facilitate creating IO filters/pipelines
+
+## KNOWN BUGS/LIMITATIONS
+
+* None at this time
+
+## SYNOPSIS
+
+More examples can be found in the `examples` directory of the source
+distribution.
+
+A simple ROT13 codec:
+
+```ruby
+require 'io/like'
+require 'io/like_helpers/delegated_io'
+require 'io/like_helpers/io_wrapper'
+
+include IO::LikeHelpers
+
+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)
+
+    super(@rot13_filter, autoclose: true, **kwargs)
+  end
+
+  protected
+
+  def rot13_filter
+    flush if writable?
+    @rot13_filter
+  end
+end
+
+class ROT13Filter < DelegatedIO
+  def initialize(delegate, autoclose: true, **kwargs)
+    if IO === delegate
+      delegate = IOWrapper.new(delegate, autoclose: autoclose)
+      autoclose = true
+    end
+
+    super(delegate, autoclose: autoclose, **kwargs)
+  end
+
+  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
+
+  def write(buffer, length: buffer.bytesize)
+    super(encode_rot13(buffer[0, length]), length: length)
+  end
+
+  private
+
+  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
+
+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
+
+  # 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
+
+  # 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
+
+* None
+
+## INSTALL
+
+    $ gem install io-like
+
+## DEVELOPERS
+
+After checking out the source, run:
+
+    $ bundle install
+    $ bundle exec rake test yard
+
+This will install all dependencies, run the tests/specs, and generate the
+documentation.
+
+## AUTHORS and CONTRIBUTORS
+
+Thanks to all contributors.  Without your help this project would not exist.
+
+* Jeremy Bopp :: jeremy@bopp.net
+* Jarred Holman :: jarred.holman@gmail.com
+* Grant Gardner :: grant@lastweekend.com.au
+* Jordan Pickwell :: jpickwell@users.noreply.github.com
+
+## CONTRIBUTING
+
+Contributions for bug fixes, documentation, extensions, tests, etc. are
+encouraged.
+
+1. Clone the repository.
+2. Fix a bug or add a feature.
+3. Add tests for the fix or feature.
+4. Make a pull request.
+
+### CODING STYLE
+
+The following points are not necessarily set in stone but should rather be used
+as a good guideline.  Consistency is the goal of coding style, and changes will
+be more easily accepted if they are consistent with the rest of the code.
+
+* **File Encoding**
+  * UTF-8
+* **Indentation**
+  * Two spaces; no tabs
+* **Line length**
+  * Limit lines to a maximum of 80 characters
+* **Comments**
+  * Document classes, attributes, methods, and code
+* **Method Calls with Arguments**
+  * Use `a_method(arg, arg, etc)`; **not** `a_method( arg, arg, etc )`,
+    `a_method arg, arg, etc`, or any other variation
+* **Method Calls without Arguments**
+  * Use `a_method`; avoid parenthesis
+* **String Literals**
+  * Use single quotes by default
+  * Use double quotes when interpolation is necessary
+  * Use `%{...}` and similar when embedding the quoting character is cumbersome
+* **Blocks**
+  * `do ... end` for multi-line blocks and `{ ... }` for single-line blocks
+* **Boolean Operators**
+  * Use `&&` and `||` for boolean tests; avoid `and` and `or`
+* **In General**
+  * Try to follow the flow and style of the rest of the code
+
+## LICENSE
+
+```
+(The MIT License)
+
+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
+'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.
+```
+
+## RUBYSPEC LICENSE
+
+Files under the `rubyspec` directory are copied in whole from the Rubyspec
+project.
+
+```
+Copyright (c) 2008 Engine Yard, Inc. All rights reserved.
+
+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.
+```