io-like 0.3.0 → 0.3.1

data/.yardopts

@@ -0,0 +1 @@
+--protected --private --plugin redcarpet-ext --main README.md lib/**/*.rb - NEWS.md LICENSE LICENSE-rubyspec

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) 2020 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,4 +1,4 @@
-= 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.
@@ -6,25 +6,30 @@ 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.
 
 
-== v0.3.0 (2009/04/29)
+## 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,269 @@
+# 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.
+
+## LINKS
+
+* Homepage :: http://github.com/javanthropus/io-like
+* Documentation :: http://rdoc.info/gems/io-like/frames
+* Source :: http://github.com/javanthropus/io-like
+
+## 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.
+
+## FEATURES
+
+* All standard Ruby 1.8.6 IO operations.
+* Buffered operations.
+* Configurable buffer size.
+
+## 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.
+
+## SYNOPSIS
+
+More examples can be found in the `examples` directory of the source
+distribution.
+
+A simple ROT13 codec:
+
+```ruby
+require 'io/like'
+
+class ROT13Filter
+  include IO::Like
+
+  def self.open(delegate_io)
+    filter = new(delegate_io)
+    return filter unless block_given?
+
+    begin
+      yield(filter)
+    ensure
+      filter.close unless filter.closed?
+    end
+  end
+
+  def initialize(delegate_io)
+    @delegate_io = delegate_io
+  end
+
+  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
+  end
+
+  def unbuffered_read(length)
+    encode_rot13(@delegate_io.sysread(length))
+  end
+
+  def unbuffered_seek(offset, whence = IO::SEEK_SET)
+    @delegate_io.sysseek(offset, whence)
+  end
+
+  def unbuffered_write(string)
+    @delegate_io.syswrite(encode_rot13(string))
+  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')
+  end
+end
+
+File.open('normal_file.txt') do |f|
+  ROT13Filter.open(f) do |rot13|
+    puts(rot13.read)                      # -> Guvf vf n grfg
+  end
+end
+
+File.open('rot13_file.txt') do |f|
+  ROT13Filter.open(f) do |rot13|
+    puts(rot13.read)                      # -> This is a test
+  end
+end
+
+File.open('normal_file.txt') do |f|
+  ROT13Filter.open(f) do |rot13|
+    rot13.pos = 5
+    puts(rot13.read)                      # -> vf n grfg
+  end
+end
+
+File.open('rot13_file.txt') do |f|
+  ROT13Filter.open(f) do |rot13|
+    rot13.pos = 5
+    puts(rot13.read)                      # -> is a test
+  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
+    end
+  end
+end
+```
+
+## REQUIREMENTS
+
+* None
+
+## 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:
+
+    $ 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) 2020 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 whole or in part 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.
+```

data/Rakefile

@@ -0,0 +1,228 @@
+# encoding: UTF-8
+# -*- ruby -*-
+
+require 'rubygems'
+
+require 'erb'
+require 'rake/testtask'
+require 'rubygems/package_task'
+require 'rake/clean'
+require 'yard'
+
+# Load the gemspec file for this project.
+GEMSPEC = Dir['*.gemspec'].first
+SPEC = eval(File.read(GEMSPEC), nil, GEMSPEC)
+
+# A dynamically generated list of files that should match the manifest (the
+# combined contents of SPEC.files and SPEC.test_files).  The idea is for this
+# list to contain all project files except for those that have been explicitly
+# excluded.  This list will be compared with the manifest from the SPEC in order
+# to help catch the addition or removal of files to or from the project that
+# have not been accounted for either by an exclusion here or an inclusion in the
+# SPEC manifest.
+#
+# NOTE:
+# It is critical that the manifest is *not* automatically generated via globbing
+# and the like; otherwise, this will yield a simple comparison between
+# redundantly generated lists of files that probably will not protect the
+# project from the unintentional inclusion or exclusion of files in the
+# distribution.
+PKG_FILES = FileList.new(Dir.glob('**/*', File::FNM_DOTMATCH)) do |files|
+  # Exclude anything that doesn't exist as well as directories.
+  files.exclude {|file| ! File.exist?(file) || File.directory?(file)}
+  # Exclude Git administrative files.
+  files.exclude(%r{(^|[/\\])\.git(ignore|modules|keep)?([/\\]|$)})
+  # Exclude editor swap/temporary files.
+  files.exclude('**/.*.sw?')
+  # Exclude gemspec files.
+  files.exclude('*.gemspec')
+  # Exclude the README template file.
+  files.exclude('README.md.erb')
+  # Exclude resources for bundler.
+  files.exclude('Gemfile', 'Gemfile.lock')
+  files.exclude(%r{^.bundle([/\\]|$)})
+  files.exclude(%r{^vendor/bundle([/\\]|$)})
+  # Exclude generated content, except for the README file.
+  files.exclude(%r{^(pkg|doc|.yardoc)([/\\]|$)})
+  # Exclude examples.
+  files.exclude(%r{^examples([/\\]|$)})
+  # Exclude Rubinius compiled Ruby files.
+  files.exclude('**/*.rbc')
+  files.exclude('.rbx/**/*')
+end
+
+# Make sure that :clean and :clobber will not whack the repository files.
+CLEAN.exclude('.git/**')
+# Vim swap files are fair game for clean up.
+CLEAN.include('**/.*.sw?')
+
+# Returns the value of the VERSION environment variable as a Gem::Version object
+# assuming it is set and a valid Gem version string.  Otherwise, raises an
+# exception.
+def get_version_argument
+  version = ENV['VERSION']
+  if version.to_s.empty?
+    raise "No version specified: Add VERSION=X.Y.Z to the command line"
+  end
+  begin
+    Gem::Version.create(version.dup)
+  rescue ArgumentError
+    raise "Invalid version specified in `VERSION=#{version}'"
+  end
+end
+
+# Performs an in place, per line edit of the file indicated by _path_ by calling
+# the sub method on each line and passing _pattern_, _replacement_, and _b_ as
+# arguments.
+def file_sub(path, pattern, replacement = nil, &b)
+  tmp_path = "#{path}.tmp"
+  File.open(path) do |infile|
+    File.open(tmp_path, 'w') do |outfile|
+      infile.each do |line|
+        outfile.write(line.sub(pattern, replacement, &b))
+      end
+    end
+  end
+  File.rename(tmp_path, path)
+end
+
+# Updates the version string in the gemspec file to the string in _version_.
+def set_version(version)
+  file_sub(GEMSPEC, /(\.version\s*=\s*).*/, "\\1'#{version}'")
+end
+
+# Returns a string that is line wrapped at word boundaries, where each line is
+# no longer than _line_width_ characters.
+#
+# This is mostly lifted directly from ActionView::Helpers::TextHelper.
+def word_wrap(text, line_width = 80)
+  text.split("\n").collect do |line|
+    line.length > line_width ?
+      line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip :
+      line
+  end * "\n"
+end
+
+desc 'Alias for build:gem'
+task :build => 'build:gem'
+
+# Build related tasks.
+namespace :build do
+  # Ensure that the manifest is consulted when building the gem.  Any
+  # generated/compiled files should be available at that time.
+  task :gem => :check_manifest
+
+  # Create the gem and package tasks.
+  Gem::PackageTask.new(SPEC).define
+
+  desc 'Verify the manifest'
+  task :check_manifest do
+    manifest_files = (SPEC.files + SPEC.test_files).sort.uniq
+    pkg_files = PKG_FILES.sort.uniq
+    if manifest_files != pkg_files then
+      common_files = manifest_files & pkg_files
+      manifest_files -= common_files
+      pkg_files -= common_files
+      message = ["The manifest does not match the automatic file list."]
+      unless manifest_files.empty? then
+        message << "  Extraneous files:\n    " + manifest_files.join("\n    ")
+      end
+      unless pkg_files.empty?
+        message << "  Missing files:\n    " + pkg_files.join("\n    ")
+      end
+      raise message.join("\n")
+    end
+  end
+
+  # Creates the README.md file from a template, the license files, and the
+  # gemspec contents.
+  file 'README.md' => ['README.md.erb', 'LICENSE', 'LICENSE-rubyspec', GEMSPEC] do
+    spec = SPEC
+    File.open('README.md', 'w') do |readme|
+      readme.write(
+        ERB.new(File.read('README.md.erb'), nil, '-').result(binding)
+      )
+    end
+  end
+end
+
+# Ensure that the clobber task also clobbers package files.
+task :clobber => 'build:clobber_package'
+
+# Ensure that the README file is (re)generated before generating documentation.
+task :yard => 'README.md'
+# Create the documentation task.
+YARD::Rake::YardocTask.new
+
+# Gem related tasks.
+namespace :gem do
+  desc 'Alias for build:gem'
+  task :build => 'build:gem'
+
+  desc 'Publish the gemfile'
+  task :publish => ['version:check', :test, 'repo:tag', :build] do
+    sh "gem push pkg/#{SPEC.name}-#{SPEC.version}*.gem"
+  end
+end
+
+# Create the test task.
+desc 'Run tests'
+task :test do
+  sh "mspec"
+end
+
+# Version string management tasks.
+namespace :version do
+  desc 'Set the version for the project to a specified version'
+  task :set do
+    set_version(get_version_argument)
+  end
+
+  desc 'Set the version for the project back to 0.0.0'
+  task :reset do
+    set_version('0.0.0')
+  end
+
+  desc 'Check that all version strings are correctly set'
+  task :check => ['version:check:spec', 'version:check:news']
+
+  namespace :check do
+    desc 'Check that the version in the gemspec is correctly set'
+    task :spec do
+      version = get_version_argument
+      if version != SPEC.version
+        raise "The given version `#{version}' does not match the gemspec version `#{SPEC.version}'"
+      end
+    end
+
+    desc 'Check that the NEWS.md file mentions the version'
+    task :news do
+      version = get_version_argument
+      begin
+        File.open('NEWS.md') do |news|
+          unless news.each_line.any? {|l| l =~ /^## v#{Regexp.escape(version.to_s)} /}
+            raise "The NEWS.md file does not mention version `#{version}'"
+          end
+        end
+      rescue Errno::ENOENT
+        raise 'No NEWS.md file found'
+      end
+    end
+  end
+end
+
+# Repository and workspace management tasks.
+namespace :repo do
+  desc 'Tag the current HEAD with the version string'
+  task :tag => :check_workspace do
+    version = get_version_argument
+    sh "git tag -s -m 'Release v#{version}' v#{version}"
+  end
+
+  desc 'Ensure the workspace is fully committed and clean'
+  task :check_workspace => ['README.md'] do
+    unless `git status --untracked-files=all --porcelain`.empty?
+      raise 'Workspace has been modified.  Commit pending changes and try again.'
+    end
+  end
+end