stream 0.5.4 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55354ecc39933e7f4be1b3b1eaa9bcfec109b00346f739e2f6c675a333ed17e9
-  data.tar.gz: aab007abb0bf1bf998be99a9806d3e3d9a8f305a422ce01ac83ea586b42a778a
+  metadata.gz: 1a1851af382462908d89f216b7b68c4e12a471bf66c8b95f68a8770bce964d5c
+  data.tar.gz: cae0261438776cd1b62c70686ec6a9983b45ecabc2476b37d88b9c6a43868272
 SHA512:
-  metadata.gz: 416c8fe937cc016744b8325bd3f15a6210a51fe17900de8e1db8b405ef5793cd2344ff3f0e9b0a3e336bf71c1497b9f84137238f4f92431fa861056f6a34646c
-  data.tar.gz: c07f8c66b7ca2d3a3e7c355b9b7bdbb6bd3151c9871159b0c92376773a732b9fdbabc2e1727f6b4c822b4412aa67a17f0601afd969f50ecd1a9751618e4c72e3
+  metadata.gz: ae065f33f579bde4192dfb75f4fc6dd57f20f40708c1614eb236364e4cf61b5848e11f2fa00e29c54f6b63af37135d8c5dd3782336d02c43b50d18742b29d121
+  data.tar.gz: 673f7510857e58e5f31b07edf304cce64a1f999f5433ba7c4305dd0ae4eb27aeb01135ab5be314155b22053a80915e91bfc3451e3860a74da710137bbfedc4ef

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.5.6](https://github.com/monora/stream/compare/v0.5.5...v0.5.6) (2026-05-10)
+
+
+### Bug Fixes
+
+* convert README to Markdown, add copyright, fix badges, clean up ([#16](https://github.com/monora/stream/issues/16)) ([9716019](https://github.com/monora/stream/commit/97160196497cb568ae2558b03d6ac4fc0e267a65))

data/Gemfile.lock

@@ -1,19 +1,15 @@
 PATH
   remote: .
   specs:
-    stream (0.5.4)
-      generator
+    stream (0.5.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    generator (0.0.1)
-    power_assert (1.1.3)
-    rake (12.3.2)
-    rdoc (6.1.1)
-    test-unit (3.2.9)
+    power_assert (3.0.1)
+    rake (13.4.2)
+    test-unit (3.7.7)
       power_assert
-    yard (0.9.16)
 
 PLATFORMS
   ruby
@@ -21,10 +17,8 @@ PLATFORMS
 
 DEPENDENCIES
   rake
-  rdoc
   stream!
   test-unit
-  yard
 
 BUNDLED WITH
-   2.3.8
+   2.5.22

data/LICENSE

@@ -1,3 +1,7 @@
+Copyright (c) 2002-2026 Horst Duchene <monora@gmail.com>
+
+stream is distributed under the same license as Ruby.
+
 Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
 You can redistribute it and/or modify it under either the terms of the
 2-clause BSDL (see the file BSDL), or the conditions below:

data/README.md

@@ -0,0 +1,209 @@
+[![Build Status](https://github.com/monora/stream/actions/workflows/ruby.yml/badge.svg)](https://github.com/monora/stream/actions/workflows/ruby.yml)
+[![Version](https://img.shields.io/gem/v/stream.svg)](https://rubygems.org/gems/stream)
+
+# Extended External Iterators (forward and backward)
+
+## Description
+
+Module `Stream` defines an interface for [external
+iterators](https://wiki.c2.com/?ExternalIterator). A stream can be seen
+as an iterator on a sequence of objects `x1,...,xn`. The state of the
+stream is uniquely determined by the following methods:
+
+* `at_beginning?`
+* `at_end?`
+* `current`
+* `peek`
+
+State changes are done with the following operations:
+
+* `set_to_begin`
+* `set_to_end`
+* `forward`
+* `backward`
+
+With the help of the method `current_edge` the state of a stream `s` can be
+exactly defined
+
+```
+s.current_edge == [s.current, s.peek]
+```
+
+If `s` a stream on `[x1,...,xn]`. Consider the edges `[xi,xi+1]` i=1,...,n
+and `[x0,x1]` and `[xn,xn+1]` (x0 and xn+1 are helper elements to define
+the boundary conditions). Then if `s` is non empty, the following
+conditions must be true:
+
+```
+s.at_beginning? <=> s.current_edge == [x0,x1]
+s.at_end?       <=> s.current_edge == [xn,xn+1]
+s.empty?        <=> s.at_beginning? && s.at_end? <=> s.current_edge == [x0,x1] <=> n = 0
+s.set_to_end    => s.at_end?
+s.set_to_begin  => s.at_beginning?
+```
+
+If `0 <= i < n` and `s.current_edge == [xi, xi+1]`, then:
+
+```
+[s.forward, s.current_edge] == [xi+1, [xi+1, xi+2]]
+```
+
+If `1 <= i < n` and `s.current_edge == [xi, xi+1]`, then:
+
+```
+[s.backward, s.current_edge] == [xi, [xi-1, xi]]
+```
+
+The result of `peek` is the same as of `forward` without changing state. The result of
+`current` is the same as of `backward` without changing state.
+
+Module `Stream` includes `Enumerable` implementing `each` in the obvious way.
+
+Not every stream needs to implement `backward` and `at_beginning?`
+thus being not reversable. If they are reversable `peek` can easily be
+implemented using `forward` and `backward`, as is done in module
+`Stream`. If a stream is not reversable all derived streams provided
+by the stream module (filter, mapping, concatenation) can be used
+anyway. Explicit or implicit (via `peek` or `current`) uses of `backward`
+would throw a `NotImplementedError`.
+
+Classes implementing the stream interface must implement the following
+methods:
+
+* `basic_forward`
+* `basic_backward`
+* `at_end?`
+* `at_beginning?`
+
+The methods `set_to_end` and `set_to_begin` are by default implemented as:
+
+```
+set_to_end   :  until at_end?; do basic_forward end
+set_to_begin :  until at_beginning?; do basic_backward end
+```
+
+The methods `forward` and `backward` are by default implemented as:
+
+```
+forward:  raise EndOfStreamException if at_end?; basic_forward.
+backward: raise EndOfStreamException if at_beginning?; basic_backward
+```
+
+Thus subclasses must only implement **four** methods. Efficiency sometimes
+demands better implementations.
+
+There are several concrete classes implementing the stream interface:
+
+* `Stream::EmptyStream` (boring)
+* `Stream::CollectionStream` created by the method `Array#create_stream`
+* `Stream::FilteredStream` created by the method `Stream#filtered`
+* `Stream::ReversedStream` created by the method `Stream#reverse`
+* `Stream::ConcatenatedStream` created by the method `Stream#concatenate`
+* `Stream::ImplicitStream` using closures for the basic methods to implement
+
+## Installation
+
+```bash
+gem install stream
+```
+
+or download the latest sources from the git repository
+<https://github.com/monora/stream>.
+
+## Examples
+
+### Iterate over three streams
+
+```ruby
+g = ('a'..'f').create_stream
+h = (1..10).create_stream
+i = (10..20).create_stream
+
+until g.at_end? || h.at_end? || i.at_end?
+  p [g.forward, h.forward, i.forward]
+end
+```
+
+Output:
+
+```
+["a", 1, 10]
+["b", 2, 11]
+["c", 3, 12]
+["d", 4, 13]
+["e", 5, 14]
+["f", 6, 15]
+```
+
+### Concatenate file streams
+
+```ruby
+def filestream fname
+  Stream::ImplicitStream.new { |s|
+    f = open(fname)
+    s.at_end_proc = proc {f.eof?}
+    s.forward_proc = proc {f.readline}
+    # Need not implement backward moving to use the framework
+  }
+end
+
+(filestream("/etc/passwd") + ('a'..'f').create_stream + filestream("/etc/group")).each do |l|
+  puts l
+end
+```
+
+### Two filtered collection streams concatenated and reversed
+
+```ruby
+def newstream; (1..6).create_stream; end
+s = newstream.filtered { |x| x % 2 == 0 } + newstream.filtered { |x| x % 2 != 0 }
+s = s.reverse
+puts "Contents      : #{s.to_a.join ' '}"
+puts "At end?       : #{s.at_end?}"
+puts "At beginning? : #{s.at_beginning?}"
+puts "2xBackwards   : #{s.backward} #{s.backward}"
+puts "Forward       : #{s.forward}"
+puts "Peek          : #{s.peek}"
+puts "Current       : #{s.current}"
+puts "set_to_begin  : Peek=#{s.set_to_begin;s.peek}"
+```
+
+Output:
+
+```
+Contents      : 5 3 1 6 4 2
+At end?       : true
+At beginning? : false
+2xBackwards   : 2 4
+Forward       : 4
+Peek          : 2
+Current       : 4
+set_to_begin  : Peek=5
+```
+
+### An infinite stream (do not use `set_to_end`!)
+
+```ruby
+def randomStream
+  Stream::ImplicitStream.new { |s|
+    s.set_to_begin_proc = proc {srand 1234}
+    s.at_end_proc = proc {false}
+    s.forward_proc = proc {rand}
+  }
+end
+s = randomStream.filtered { |x| x >= 0.5 }.collect { |x| sprintf("%5.2f",x*100) }
+puts "5 random numbers: #{(1..5).collect {|x| s.forward}}\n"
+```
+
+Output:
+
+```
+5 random numbers: ["62.21", "78.54", "78.00", "80.19", "95.81"]
+```
+
+## Copying
+
+stream is Copyright (c) 2002-2026 by Horst Duchene.
+
+It is free software, and may be redistributed under the terms specified
+in the [LICENSE](LICENSE) file.

data/Rakefile

@@ -1,25 +1,12 @@
 # Rakefile for stream   -*- ruby -*-
 
-require 'rubygems'
 require 'bundler/setup'
-require 'rubygems/package_task'
 
 require 'rake/testtask'
-require 'rake/clean'
-require 'yard'
-
-$:.unshift File.join(File.dirname(__FILE__), 'lib')
-require 'stream' # require module to STREAM_VERSION
-
-SRC_RB = FileList['lib/*.rb']
-
-# The default task is run if rake is given no explicit arguments.
 
 desc "Default Task"
 task :default => :test
 
-# Define a test task.
-
 Rake::TestTask.new do |t|
   t.libs << 'test'
   t.pattern = 'test/test*.rb'
@@ -28,23 +15,4 @@ end
 
 task :test
 
-# Define a test that will run all the test targets.
-desc "Run all test targets"
-task :testall => [:test ]
-
-# Git tagging
-
-desc "Commit all changes as a new version commit. Tag the commit with v<version> tag"
-task :tag do
-  puts "Committing and tagging version #{STREAM_VERSION}"
-  `git commit -am 'Version #{STREAM_VERSION}'`
-  `git tag 'v#{STREAM_VERSION}'`
-end
-
-# Documentation
-
-YARD::Rake::YardocTask.new
-
-# Tasks for building and installing Stream gem.
-
 Bundler::GemHelper.install_tasks

data/lib/stream/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Stream
+  VERSION = '0.5.6'
+end

data/lib/stream.rb

@@ -1,4 +1,6 @@
-STREAM_VERSION = '0.5.4'.freeze
+# frozen_string_literal: true
+
+require 'stream/version'
 
 ##
 # Module Stream defines an interface for an external Iterator which
@@ -24,15 +26,17 @@ module Stream
   end
 
   # Move forward one position. Returns the _target_ of current_edge.
-  # Raises Stream::EndOfStreamException if at_end? is true.
+  # @raise [EndOfStreamException] if at_end? is true
+  # @return [Object] the next element
   def forward
     raise EndOfStreamException if at_end?
 
     basic_forward
   end
 
-  # Move backward one position. Returns the _source_ of current_edge. Raises
-  # Stream::EndOfStreamException if at_beginning? is true.
+  # Move backward one position. Returns the _source_ of current_edge.
+  # @raise [EndOfStreamException] if at_beginning? is true
+  # @return [Object] the previous element
   def backward
     raise EndOfStreamException if at_beginning?
 
@@ -79,6 +83,8 @@ module Stream
   # This is similar to #detect, but starts the search from the
   # current position. #detect, which is inherited from Enumerable uses
   # #each, which implicitly calls #set_to_begin.
+  # @yield [element] each element in forward direction
+  # @return [Object, nil] the first matching element, or nil
   def move_forward_until
     until at_end?
       element = basic_forward
@@ -89,6 +95,8 @@ module Stream
 
   # Move backward until the boolean block is not false and returns the element
   # found. Returns nil if no object matches.
+  # @yield [element] each element in backward direction
+  # @return [Object, nil] the first matching element, or nil
   def move_backward_until
     until at_beginning?
       element = basic_backward
@@ -192,6 +200,7 @@ module Stream
     attr_reader :pos
 
     # Creates a new CollectionStream for the indexable sequence _seq_.
+    # @param seq [Array] an integer-indexed collection
     def initialize(seq)
       @seq = seq
       set_to_begin
@@ -252,6 +261,7 @@ module Stream
 
     # Create a new IntervalStream with upper bound _stop_. stop - 1 is the last
     # element. By default _stop_ is zero which means that the stream is empty.
+    # @param stop [Integer] exclusive upper bound; stream yields 0..stop-1
     def initialize(stop = 0)
       @stop = stop - 1
       set_to_begin
@@ -617,6 +627,8 @@ module Stream
     #
     # If a block is given to new, than it is called with the new ImplicitStream
     # stream as parameter letting the client overwriting the default blocks.
+    # @param other_stream [Stream, nil] optional stream to wrap
+    # @yield [self] the new ImplicitStream instance for customization
     def initialize(other_stream = nil)
       # Initialize with defaults
       @at_beginning_proc = proc { true }
@@ -674,7 +686,9 @@ module Stream
 
   ##
   # Return a Stream::FilteredStream which iterates over all my elements
-  # satisfying the condition specified  by the block.
+  # satisfying the condition specified by the block.
+  # @yield [element] filter predicate
+  # @return [FilteredStream]
   def filtered(&block)
     FilteredStream.new(self, &block)
   end
@@ -687,6 +701,8 @@ module Stream
   # Create a Stream::MappedStream wrapper on self. Instead of returning the
   # stream element on each move, the value of calling _mapping_ is returned
   # instead. See Stream::MappedStream for examples.
+  # @yield [element] mapping block applied to each element
+  # @return [MappedStream]
   def collect(&mapping)
     MappedStream.new(self, &mapping)
   end
@@ -708,8 +724,10 @@ module Stream
     collect(&mapping).concatenate
   end
 
-  # Create a Stream::ConcatenatedStream by concatenatating the receiver and
-  # _other_stream_
+  # Create a Stream::ConcatenatedStream by concatenating the receiver and
+  # _other_stream_.
+  # @param other [Stream] the stream to append
+  # @return [ConcatenatedStream]
   #
   #  (%w(a b c).create_stream + [4,5].create_stream).to_a
   #  ==> ["a", "b", "c", 4, 5]

data/test/test_helper.rb

@@ -1,2 +1 @@
-require 'rubygems'
 require 'test/unit'

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: stream
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.5.6
 platform: ruby
 authors:
 - Horst Duchene
-autorequire: stream
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-02 00:00:00.000000000 Z
+date: 2026-05-10 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: generator
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  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
@@ -38,34 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  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: rdoc
-  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: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -84,17 +42,18 @@ description: Module Stream defines an interface for external iterators.
 email: monora@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files:
-- README.rdoc
+extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - examples/examples.rb
 - examples/streamtester.rb
 - lib/stream.rb
+- lib/stream/version.rb
 - test/test_helper.rb
 - test/teststream.rb
 homepage: https://github.com/monora/stream
@@ -102,12 +61,7 @@ licenses:
 - ruby
 metadata: {}
 post_install_message:
-rdoc_options:
-- "--title"
-- stream - Extended External Iterators
-- "--main"
-- README.rdoc
-- "--line-numbers"
+rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -121,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: stream - Extended External Iterators

data/README.rdoc

@@ -1,172 +0,0 @@
-{<img src="https://github.com/monora/stream/actions/workflows/ruby.yml/badge.svg" alt="Build Status" />}[https://github.com/monora/stream/actions/workflows/ruby.yml]
-
-= Extended External Iterators (forward and backward)
-
-== Description
-
-Module Stream defines an interface for external iterators. A stream can be
-seen as an iterator on a sequence of objects x1,...,xn. The state of the
-stream is uniquely determined by the following methods:
-
-* at_beginning?
-* at_end?
-* current
-* peek
-
-State changes are done with the following operations:
-
-* set_to_begin
-* set_to_end
-* forward
-* backward
-
-With the help of the method current_edge the state of a stream s can be
-exactly defined
-
- s.current_edge == [s.current, s.peek]
-
-If s a stream on [x1,...,xn]. Consider the edges [xi,xi+1] i=1,...,n and
-[x0,x1] and [xn,xn+1] (x0 and xn+1 are helper elements to define the boundary
-conditions). Then if s is non empty, the following conditions must be true:
-
- s.at_beginning? <=> s.current_edge == [x0,x1]
- s.at_end? <=> s.current_edge == [xn,xn+1]
- s.isEmpty? <=> s.at_beginning? && s.at_end? <=> s.current_edge == [x0,x1] <=> n = 0
- s.set_to_end => s.at_end?
- s.set_to_begin => s.at_beginning?
-
-If 0 <= i < n and s.current_edge == [xi, xi+1] , then:
-
- [s.forward, s.current_edge] == [xi+1, [xi+1, xi+2]]
-
-If 1 <= i < n and s.current_edge == [xi, xi+1] , then:
-
- [s.backward, s.current_edge] == [xi, [xi-1, xi]]
-
-The result of peek is the same as of forward without changing state. The result of
-current is the same as of backward without changing state.
-
-Module Stream includes Enumerable implementing #each in the obvious way.
-
-Not every stream needs to implement #backward and #at_beginning? thus being
-not reversable. If they are reversable peek can easily be implemented using
-forward and backward, as is done in module Stream. If a stream is not
-reversable all derived streams provided by the stream module (filter,
-mapping, concatenation) can be used anyway. Explicit or implicit (via peek or
-current) uses of backward would throw a NotImplementedError.
-
-Classes implementing the stream interface must implement the following methods:
-
-* basic_forward
-* basic_backward
-
-* at_end?
-* at_beginning?
-
-The methods set_to_end and set_to_begin are by default implemented as:
-
- set_to_end   :  until at_end?; do basic_forward end
- set_to_begin :  until at_beginning?; do basic_backward end
-
-The methods forward and backward are by default implemented as:
-
- forward:	   raise EndOfStreamException if at_end?; basic_forward.
- backward:   raise EndOfStreamException if at_beginning?; basic_backward
-
-Thus subclasses must only implement *four* methods. Efficiency sometimes
-demands better implementations.
-
-There are several concrete classes implementing the stream interface:
-
-* Stream::EmptyStream (boring)
-* Stream::CollectionStream created by the method Array#create_stream
-* Stream::FilteredStream created by the method Stream#filtered
-* Stream::ReversedStream created by the method Stream#reverse
-* Stream::ConcatenatedStream created by the method Stream#concatenate
-* Stream::ImplicitStream using closures for the basic methods to implement
-
-== Download
-
-The latest version of stream.rb can be found at
-
-* http://github.com/monora/stream
-
-== Installation
-
-=== Normal Installation
-
-You can install stream with the following command.
-
-  % ruby install.rb
-
-from its distribution directory.
-
-=== GEM Installation
-
-Download the GEM file and install it with ..
-
-   gem -i stream-VERSION.gem
-
-Use the correct version number for VERSION (e.g. 0.5).  You may need
-root privileges to install.
-
-== See also
-
-* Streams in Smalltalk: http://wiki.cs.uiuc.edu/PatternStories/FunWithStreams
-* Simon Strandgaards iterator.rb[http://aeditor.rubyforge.org/iterator/files/iterator_rb.html]
-
-== Examples
-
-  g = ('a'..'f').create_stream
-  h = (1..10).create_stream
-  i = (10..20).create_stream
-
-  until g.at_end? || h.at_end? || i.at_end?
-    p [g.forward, h.forward, i.forward]
-  end
-
-  def filestream fname
-    Stream::ImplicitStream.new { |s|
-      f = open(fname)
-      s.at_end_proc = proc {f.eof?}
-      s.forward_proc = proc {f.readline}
-      # Need not implement backward moving to use the framework
-    }
-  end
-
-  (filestream("/etc/passwd") + ('a'..'f').create_stream + filestream("/etc/group")).each do |l|
-    puts l
-  end
-
-  puts "\nTwo filtered collection streams concatenated and reversed:\n\n"
-
-  def newstream; (1..6).create_stream; end
-  s = newstream.filtered { |x| x % 2 == 0 } + newstream.filtered { |x| x % 2 != 0 }
-  s = s.reverse
-  puts "Contents      : #{s.to_a.join ' '}"
-  puts "At end?       : #{s.at_end?}"
-  puts "At beginning? : #{s.at_beginning?}"
-  puts "2xBackwards   : #{s.backward} #{s.backward}"
-  puts "Forward       : #{s.forward}"
-  puts "Peek          : #{s.peek}"
-  puts "Current       : #{s.current}"
-  puts "set_to_begin    : Peek=#{s.set_to_begin;s.peek}"
-
-  # an infinite stream (do not use set_to_end!)
-  def randomStream
-    Stream::ImplicitStream.new { |s|
-      s.set_to_begin_proc = proc {srand 1234}
-      s.at_end_proc = proc {false}
-      s.forward_proc = proc {rand}
-    }
-  end
-  s = randomStream.filtered { |x| x >= 0.5 }.collect { |x| sprintf("%5.2f ",x*100) }
-  puts "5 random numbers: #{(1..5).collect {|x| s.forward}}\n" # =>
-
-    5 random numbers: 74.05 94.80 87.87 86.07 83.70
-
-== Other Stuff
-
-Author:: Horst Duchene
-License:: Copyright (c) 2001, 2013, 2016, 2020 Horst Duchene
-Released under the same license as Ruby