seq 0.1.0

data/LICENCE

@@ -0,0 +1,7 @@
+Copyright (c) 2011 Joshua Hawxwell
+
+ 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,95 @@
+# seq
+
+Defines a Seq class, which cycles over elements in an array.
+
+```ruby
+s = Seq.new([1,2])
+s.next #=> 1
+s.next #=> 2
+s.next #=> 1
+# and so on forever
+```
+
+They can be constrained to only return `n` items,
+
+```ruby
+s = Seq.new([1,2,3], 2)
+s.next #=> 1
+s.next #=> 2
+s.next #=> nil
+s.next #=> nil
+```
+
+and can start from an offset.
+
+```ruby
+s = Seq.new([1,2,3], 2, 1)
+s.next #=> 2
+s.next #=> 3
+s.next #=> nil
+s.next #=> nil
+```
+
+You can also provide a different default (as opposed to `nil`).
+
+```ruby
+list = %w(a b c d)
+s = Seq.new(list, 3, 0, list.last)
+s.next #=> a
+s.next #=> b
+s.next #=> c
+s.next #=> d
+s.next #=> d
+```
+
+Seq has `#each` defined and includes the `Enumerable` module so the usual stuff applies.
+
+```ruby
+s = Seq.new([1,2,3,4], 10)
+s.map {|i| i * 2 } #=> [2, 4, 6, 8, 2, 4, 6, 8, 2, 4]
+s.next #=> nil
+
+# Standard methods will increment the number of items that have been returned meaning
+# you have to call #reset
+s.reset 
+s.next #=> 1
+
+# You can use special ! versions to avoid incrementing the number of cycles, but note
+# this will start and finish based on the current index and items returned. So here 
+# we are on the second item in the original list, ie. "2".
+
+s.map! {|i| i * 2 } #=> [4, 6, 8, 2, 4, 6, 8, 2, 4]
+
+# Note this only returned 9 items as we had already called #next, and it started on 2
+# which was mapped to 4.
+
+s.reset
+s.entries #=> [1, 2, 3, 4, 1, 2, 3, 4, 1, 2]
+s.reject! {|i| i < 3 } #=> [3, 4, 3, 4]
+
+s.take(4) #=> [1, 2, 3, 4]
+s.entries #=> [1, 2, 3, 4, 1, 2]
+s.reject! {|i| i < 3 } #=> [3, 4]
+```
+
+## Seq::Random
+
+A subclass of Seq which returns random elements.
+
+```ruby
+r = Seq::Random.new([1,2,3], 5)
+r.entries #=> [2, 1, 1, 3, 2]
+r.entries #=> [1, 3, 2, 3, 3]
+```
+
+## Seq::Lazy
+
+Lazily evaluates a block using starting list given.
+
+```ruby
+fibs = Seq::Lazy.new([1,1]) {|list| list[-1] + list[-2] }
+fibs.take(10) #=> [1, 1, 2, 3, 5, 8, 13, 21, 34, 55] 
+fibs.take(20) #=> [89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946, 17711, 28657, 46368, 75025, 121393, 196418, 317811, 514229, 832040]
+fibs.next! #=> 832040
+fibs.reset
+```

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+task :default => :test
+

data/lib/seq.rb

@@ -0,0 +1,137 @@
+unless defined?(Float::INFINITY)
+  # Define Float::INFINITY if not previously defined
+  Float::INFINITY = 1.0/0
+end
+
+# A Seq will cycle over a list returning a certain number of items.
+#
+# @example With number of items to return
+#
+#   s = Seq.new([1, 2], 4)
+#   s.next #=> 1
+#   s.next #=> 2
+#   s.next #=> 1
+#   s.next #=> 2
+#   s.next #=> nil
+#
+# @example With an offset
+#
+#   s = Seq.new([1, 2, 3, 4, 5], 5, 3)
+#   s.next #=> 4
+#   s.next #=> 5
+#   s.next #=> 1
+#   # etc
+#
+# @example With default value
+#
+#   s = Seq.new([1, 2], 2, 0, 2)
+#   s.next #=> 1
+#   s.next #=> 2
+#   s.next #=> 2
+#   s.next #=> 2
+#
+class Seq
+
+  # Creates a new instance of Seq.
+  #
+  # @param list [Array] List of values to cycle over
+  # @param items [Integer] Number of values to return
+  # @param offset [Integer] Index of item in +list+ to start at
+  # @param default [Object] Value to return when finished cycling
+  def initialize(list=[], items=Float::INFINITY, offset=0, default=nil)
+    @list    = list
+    @items   = items
+    @offset  = offset
+    @default = default
+    
+    self.reset
+  end
+  
+  # Resets the Seqs position to the same as when initialized.
+  def reset
+    @cycles = 0
+    @index  = @offset
+  end
+  
+  # @return Until ended it returns the next item from the list, when ended it returns 
+  #  the default item.
+  def next
+    if ended?
+      @default
+    else
+      @list[@index].tap { inc }
+    end
+  end
+  
+  # Increment the list index, the number of cycles completed and if at the end of 
+  # the list returns to the first item.
+  # 
+  # @return [Integer] Number of items that have been returned.
+  def inc
+    if @index+1 == @list.size
+      @index = 0 
+    else
+      @index += 1
+    end
+    @cycles += 1
+  end
+  
+  # Iterates over each item as returned by #next until #ended?.
+  def each
+    until ended?
+      yield self.next
+    end
+  end
+  
+  include Enumerable
+
+  # @return [Array] The items that would be returned by repeated calls to #next
+  #  until #ended?.
+  # @raise [RangeError] If #infinite?, otherwise it creates an infinite loop!
+  def entries
+    raise RangeError if infinite?
+  
+    i, c = @index, @cycles
+    r = super
+    @index, @cycles = i, c
+    r
+  end
+
+  # @return [Array] Returns the original list
+  def to_a
+    @list
+  end
+  
+  # @return Whether the Seq returns infinite items.
+  def infinite?
+    @items == Float::INFINITY
+  end
+
+  # @return Whether the Seq has returned enough items.
+  def ended?
+    @cycles >= @items
+  end
+  
+  # Any method called on a Seq with ending with !, will be caught by method
+  # missing, it will then attempt to call the non ! version but will not
+  # alter the index or number of cycles completed. 
+  def method_missing(sym, *args, &block)
+    if sym.to_s[-1] == "!" && 
+      self.respond_to?(sym.to_s[0..-2].to_sym) &&
+      ! [:infinite?, :ended?, :to_a, :entries, :inc, :reset].include?(sym.to_s[0..-2].to_sym)
+      
+      begin
+        i, c = @index, @cycles
+        self.send(sym.to_s[0..-2].to_sym, *args, &block)
+      ensure
+        @index, @cycles = i, c
+      end
+    else
+      super
+    end
+  end
+end
+
+require 'seq/lazy'
+require 'seq/random'
+require 'seq/version'

data/lib/seq/lazy.rb

@@ -0,0 +1,73 @@
+require 'seq'
+
+class Seq
+
+  # Lazy seqs evaluate a block to determine the next value when needed,
+  # this value is then saved.
+  #
+  # @example
+  #
+  #   s = Seq::Lazy.new([1]) { 1 }
+  #   s.take(3) #=> [1, 1, 1]
+  #
+  #   ns = Seq::Lazy.new([1]) {|l| l[-1] + 1 }
+  #   ns.take(5) #=> [1, 2, 3, 4, 5]
+  #
+  #   fibs = Seq::Lazy.new([1, 1]) {|l| l[-1] + l[-2] }
+  #   fibs.take(7) #=> [1, 1, 2, 3, 5, 8, 13]
+  #   fibs.take!(7) #=> [21, 34, 55, 89, 144, 233, 377]
+  #   fibs.take!(2) #=> [21, 34]
+  #
+  class Lazy < Seq
+    
+    # Creates a new Lazy seq instance.
+    #
+    # @param list [Array] Starting values
+    # @param items [Integer] Number of values to return
+    # @param offset [Integer] Index of item to start at
+    # @param default [Object] Value to return when finished cycling
+    #
+    # @yield [list] Block to be called which returns the next value in the list
+    # @yieldparam list [Array] The list calculated up to the current point
+    def initialize(list=[], items=Float::INFINITY, offset=0, default=nil, &block)
+      @list    = list
+      @items   = items
+      @block   = block
+      @offset  = offset
+      @default = default
+      
+      self.reset
+    end
+    
+    # Resets the state of the lazy seq. It also calculates any values 
+    # necessary to get to the offset.
+    def reset
+      @index  = @list.size
+      @cycles = 0
+      
+      until @list.size >= @offset
+        @list[@index] = @block.call(@list[0..@index-1])
+        @index += 1
+      end
+      
+      @index = @offset
+    end
+    
+    # @return [Object]
+    #  Until ended it returns the next item from +list+ if it exists or calculates
+    #  it then stores it in +list+, if ended it returns the default value.
+    def next
+      if ended?
+        @default
+      else
+        @index += 1
+        if @index-1 < @list.size
+          @list[@index-1]
+        else
+          @list[@index-1] = @block.call(@list)
+        end
+      end
+    end
+  
+  end
+end

data/lib/seq/random.rb

@@ -0,0 +1,34 @@
+require 'seq'
+
+class Seq
+
+  # A Random seq chooses items from the list randomly.
+  #
+  # @example
+  #
+  #   s = Seq::Random.new([1,2,3,4,5])
+  #   s.take(6) #=> [1, 4, 5, 3, 1, 2] 
+  #
+  class Random < Seq
+  
+    # Creates a new Random seq instance.
+    #
+    # @param list [Array] List of values to cycle over
+    # @param items [Integer] Number of values to return
+    # @param default [Object] Value to return when finished cycling
+    def initialize(list=[], items=Float::INFINITY, default=nil)
+      super(list, items, 0, default)
+    end
+    
+    # @return Until ended it returns a randomly selected item from the list, when 
+    #  ended it returns the default value.
+    def next
+      if ended?
+        @default
+      else
+        @list[rand(@list.size).to_i].tap { inc }
+      end
+    end
+  
+  end
+end

data/lib/seq/version.rb

@@ -0,0 +1,4 @@
+class Seq
+  # Current version
+  VERSION = "0.1.0"
+end

data/test/helper.rb

@@ -0,0 +1,8 @@
+$: << File.dirname(__FILE__)
+$: << File.dirname(__FILE__) + '/../lib'
+
+require 'seq'
+
+require 'rubygems'
+require 'minitest/unit'
+require 'minitest/autorun'

data/test/seq/lazy_test.rb

@@ -0,0 +1,25 @@
+$: << File.dirname(__FILE__) + '/..'
+require 'helper'
+
+class LazySeqTest < MiniTest::Unit::TestCase
+
+  def setup
+    @seq = Seq::Lazy.new([1, 1]) {|l| l[-1] + l[-2] }
+  end
+  
+  def test_defines_next
+    assert_equal 1, @seq.next
+    assert_equal 1, @seq.next
+    assert_equal 2, @seq.next
+    assert_equal 3, @seq.next
+    assert_equal 5, @seq.next
+    assert_equal 8, @seq.next
+    assert_equal 13, @seq.next
+  end
+  
+  def test_offset_works
+    s = Seq::Lazy.new([1], 1.0/0, 5) {|l| l.last + 1 }
+    assert_equal 6, s.next
+  end
+
+end

data/test/seq/random_test.rb

@@ -0,0 +1,24 @@
+$: << File.dirname(__FILE__) + '/..'
+require 'helper'
+
+class RandomSeqTest < MiniTest::Unit::TestCase
+
+  def setup
+    @seq = Seq::Random.new([1, 2, 3], 6)
+  end
+  
+  def test_defines_next
+    assert_includes [1,2,3], @seq.next
+    assert_includes [1,2,3], @seq.next
+    assert_includes [1,2,3], @seq.next
+    assert_includes [1,2,3], @seq.next
+    assert_includes [1,2,3], @seq.next
+    assert_includes [1,2,3], @seq.next
+    assert_equal nil, @seq.next
+  end
+  
+  def test_cycles_correct_times
+    assert_equal 6, @seq.entries.size
+  end
+
+end

data/test/seq_test.rb

@@ -0,0 +1,65 @@
+$: << File.dirname(__FILE__)
+require 'helper'
+
+class SeqTest < MiniTest::Unit::TestCase
+
+  def setup
+    @empty = Seq.new
+    @seq   = Seq.new([1, 2, 3, 4], 7, 1, "nope")
+  end
+
+  def test_can_become_array
+    assert_equal [], @empty.to_a
+    assert_equal [1, 2, 3, 4], @seq.to_a
+  end
+  
+  def test_can_become_expanded_array
+    assert_raises RangeError do 
+      @empty.entries
+    end
+    
+    assert_equal [2, 3, 4, 1, 2, 3, 4], @seq.entries
+  end
+  
+  def test_can_iterate
+    @empty.each_with_index do |a,i|
+      assert_equal a, nil
+      break if i > 3
+    end
+    
+    @seq.each_with_index do |a,i|
+      assert_equal a, case i
+        when 0 then 2
+        when 1 then 3
+        when 2 then 4
+        when 3 then 1
+        when 4 then 2
+        when 5 then 3
+        when 6 then 4
+      end
+    end
+  end
+  
+  def test_gets_next_item 
+    assert_equal nil, @empty.next
+    assert_equal nil, @empty.next
+    
+    assert_equal 2, @seq.next
+    assert_equal 3, @seq.next
+    assert_equal 4, @seq.next
+    assert_equal 1, @seq.next
+    assert_equal 2, @seq.next
+    assert_equal 3, @seq.next
+    assert_equal 4, @seq.next
+    assert_equal "nope", @seq.next
+    assert_equal "nope", @seq.next
+  end
+
+  def test_can_be_reset
+    10.times { @seq.next }
+    assert_equal "nope", @seq.next
+    @seq.reset
+    assert_equal 2, @seq.next
+  end
+
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: seq
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Joshua Hawxwell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-07-22 00:00:00.000000000 +01:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &2156880320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.1
+  type: :development
+  prerelease: false
+  version_requirements: *2156880320
+description: ! "    A Seq is created with an array, and optionally a number of elements\n
+  \   to return, an offset to start at and a default item to return when\n    ended.
+  Call #next to return the next item.\n    \n    A Seq::Random will return randomly
+  selected elements from the array.\n    A Seq::Lazy will lazily evaluate a block
+  to get the next element.\n"
+email: m@hawx.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- LICENCE
+- lib/seq/lazy.rb
+- lib/seq/random.rb
+- lib/seq/version.rb
+- lib/seq.rb
+- test/helper.rb
+- test/seq/lazy_test.rb
+- test/seq/random_test.rb
+- test/seq_test.rb
+has_rdoc: true
+homepage: http://github.com/hawx/seq
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Seqs cycle over elements of an array.
+test_files:
+- test/helper.rb
+- test/seq/lazy_test.rb
+- test/seq/random_test.rb
+- test/seq_test.rb