functional-ruby 0.7.4 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1033510698e79e8472d8fee1bc631b9d03edce14
-  data.tar.gz: f3fbc19a3c18543984cba90b64ac8508b105bd63
+  metadata.gz: 97e8113fb43fd8fda7f581f0e3bc342e66b42cdb
+  data.tar.gz: c64e9d6a0788814d50bdc87b00ca7d00caa887a5
 SHA512:
-  metadata.gz: 4d206b9ddcc7ab49f2225e8fe9a3fb638d9b35ab09a75ee6a33602d000003cf235dab1650fcc8e72accfaed3371b7254104bbae4227db16c64eaf4ea15cacb37
-  data.tar.gz: d90c081ad4efc3963d4e125d9c1867c138067d096e136c0fb0ad9d124f8438415d098a36847e877ccf9186df81906f495cecebcff55bdde7885dfb2af403a0e2
+  metadata.gz: ac1e57dac94eedaf8a94a45715ecc5757238afa8a7fe4dc24e57b3255d1ce7f1e64a3b2d562c099d0b77ca1b815778905ad561c09e46c337c1b43c0e4c4188f2
+  data.tar.gz: 4db984862cf3b281ed4251e4fd1d6f8702e015f47a348d091080f84df0479cdc3fa77ecc2eafb0c64801c7e7d8a58ca8d7a3f1dd8ef7e1006359f02e498f94d6

data/README.md

@@ -16,21 +16,50 @@ The project is hosted on the following sites:
 
 ## Introduction
 
-Three things I love are [Ruby](http://www.ruby-lang.org/en/),
+Two things I love are [Ruby](http://www.ruby-lang.org/en/) and
 [functional](https://en.wikipedia.org/wiki/Functional_programming)
-[programming](http://c2.com/cgi/wiki?FunctionalProgramming) and
-[concurrency](http://www.amazon.com/s/ref=nb_sb_noss_1?url=search-alias%3Dstripbooks&field-keywords=concurrent%20programming).
-Sadly, the first is generally not associated with the other two. First, I reject the
-assertion that Ruby is an object-oriented language. It's certainly object-based, since
+[programming](http://c2.com/cgi/wiki?FunctionalProgramming).
+Sadly, the former is generally not associated with the latter. Unfortunately,
+too many people are blinded by their belief that Ruby is an object-oriented
+language. I reject this assertion. Ruby is certainly object-based, since
 everything is an object, but entire large-scale programs can be built without ever
-defining a single class. Ruby is a true multi-paradigm language and easily supports
-many advanced functional techniques. As to concurrency, Ruby's bad reputation is
-well earned, but recent versions of Ruby have made significan improvements in that
-area. Ruby 2.0 is now a [relevant](https://blog.heroku.com/archives/2013/6/17/ruby-2-default-new-aps)
-platform for concurrent applications.
+defining a single class. But Ruby's features that support functional programming
+don't stop there.
+
+Ask ten different programmers to define the term "functional programming" and
+you will likely get ten different answers. One characteristic that will certainly
+be on all their lists is support for
+[higher](http://en.wikipedia.org/wiki/Higher-order_function)
+[order](http://learnyouahaskell.com/higher-order-functions)
+[functions](http://learnyousomeerlang.com/higher-order-functions). Put simply, a
+higher order function is any function that can take one or more functions as
+parameters and/or return a function as a result. Many functional languages,
+such as Erlang, Haskell, and Closure, support higher order functions. Higher order
+functions are a remarkable tool that can completely change the was software is
+designed. Most classicaly object-oriented languages do not support higher
+order functions. Unfortunately, Ruby does not directly support higher order
+functions. Thanksfully, Ruby *does* give us blocks, `proc`s, and `lambda`s.
+Though not strictly higher order functions, in most cases they are functionally
+equivalent.
+
+If you combine Ruby's ability to create functions sans-classes with the power
+of blocks/`proc`s/`lambda`s, Ruby code can follow just about every modern functional
+programming design paradigm. Hence, I consider Ruby to be a *multi-paradigm* language.
+Add to this Ruby's vast metaprogramming capabilities and Ruby is easily one of the
+most powerful languages in common use today.
 
 This gem is my small and humble attempt to help Ruby reach its full potential as
-a highly performant, functional programming language.
+a highly performant, functional programming language. Virtually every function in
+this library takes a block parameter. Some allow a block plus one or more `proc`
+arguments. Most operate *on* data structures rather than being buried *in* data
+structures. Finally, several of the tools in this library are Ruby implementations
+of some of my favorite features from other functional programming languages. Not
+every function is pure, but functions with side effects are easy to spot because
+they almost always have names that end in an exclamation point.
+
+My hope is that this gem will help Ruby programmers explore Ruby as a functional
+language and improve their code in ways our object oriented brethern never
+dreamed possible.
 
 ### Goals
 
@@ -48,8 +77,13 @@ My goal is to implement various functional programming patterns in Ruby. Specifi
 
 Several features from Erlang, Go, and Clojure have been implemented thus far:
 
-* Function overloading with Erlang-style [Pattern Matching](https://github.com/jdantonio/functional-ruby/blob/master/md/pattern_matching.md)
 * Interface specifications with Erlang-style [Behavior](https://github.com/jdantonio/functional-ruby/blob/master/md/behavior.md)
+* A [Catalog](https://github.com/jdantonio/functional-ruby/blob/master/md/catalog.md) class for managing sets of key/value pairs in a manner similar to Erlang's [proplists](http://www.erlang.org/doc/man/proplists.html)
+* A toolkit of [collection](https://github.com/jdantonio/functional-ruby/blob/master/md/collection.md) utilities for operating on list-like data structures
+* A set of string [inflections](https://github.com/jdantonio/functional-ruby/blob/master/md/inflect.md) borrowed from [Active Support](http://guides.rubyonrails.org/active_support_core_extensions.html#inflections)
+* Function overloading with Erlang-style [Pattern Matching](https://github.com/jdantonio/functional-ruby/blob/master/md/pattern_matching.md)
+* Tools for introspecting the runtime [Platform](https://github.com/jdantonio/functional-ruby/blob/master/md/platform.md) for information about the operating system and Ruby version
+* [Search](https://github.com/jdantonio/functional-ruby/blob/master/md/search.md) and [sort](https://github.com/jdantonio/functional-ruby/blob/master/md/sort.md) algorithms like you remember from your algorithms class, but with a functional twist
 * Several useful functional [Utilities](https://github.com/jdantonio/functional-ruby/blob/master/md/utilities.md)
 
 ### Is it any good?

data/lib/functional.rb

@@ -1,5 +1,24 @@
 require 'functional/behavior'
+require 'functional/behaviour'
+require 'functional/catalog'
+require 'functional/collection'
+require 'functional/inflect'
 require 'functional/pattern_matching'
 require 'functional/platform'
+require 'functional/search'
+require 'functional/sort'
 require 'functional/utilities'
 require 'functional/version'
+
+Infinity = 1/0.0 unless defined?(Infinity)
+NaN = 0/0.0 unless defined?(NaN)
+
+module Functional
+
+  class << self
+    include Collection
+    include Inflect
+    include Search
+    include Sort
+  end
+end

data/lib/functional/catalog.rb

@@ -0,0 +1,487 @@
+module Functional
+
+  # A collection of key/value pairs similar to a hash but ordered.
+  # Access is via index (like an array) rather than by key (like a
+  # hash). Supports duplicate keys. Indexing starts at zero.
+  class Catalog
+    include Enumerable
+
+    # Create a new Catalog from the given data. When +data+ is nil
+    # or an empty collection the resulting Catalog will be empty.
+    # When +data+ is an array, hash, or catalog array the appropriate
+    # +#from_+ factory method will be called. The +:from+ option is
+    # used to indicate the type of the source data.
+    #
+    # If a block is given each value in the from the source array will
+    # be passed to the block and the result will be stored as the value
+    # in the Catalog.
+    #
+    # @param [Array, Hash, Catalog] data the data to construct the
+    #   Catalog from
+    # @param [Hash] opts processing options
+    #
+    # @option opts [Symbol] :from the type of the data source. Valid values
+    #   are :catalog/:catalogue, :hash, :array (default :catalog).
+    def initialize(data=nil, opts={})
+
+      if block_given?
+
+        @data = []
+        data.each do |item|
+          @data << yield(item)
+        end
+
+      else
+        from = opts[:from]
+        from = :array if [:set, :list, :stack, :queue, :vector].include?(from)
+        from = "from_#{from}".to_sym
+
+        if Catalog.respond_to?(from)
+          @data = Catalog.send(from, data)
+          @data = @data.instance_variable_get(:@data)
+        elsif opts[:from].nil? && !data.nil?
+          @data = Catalog.from_catalog(data)
+          @data = @data.instance_variable_get(:@data)
+        else
+          @data = []
+        end
+      end
+    end
+
+    # Creates a new Catalog object from a hash. Each key/value pair in the
+    # hash will be converted to a key/value array in the new Catalog. If a
+    # block is given each value in the array will be passed to the block
+    # and the result will be stored as the value in the Catalog.
+    def self.from_hash(data = {})
+      collected = []
+      data.each do |key, value|
+        value = yield(value) if block_given?
+        collected << [key, value]
+      end
+      catalog = Catalog.new
+      catalog.instance_variable_set(:@data, collected)
+      return catalog
+    end
+
+    # Creates a new catalog object from an array. Each successive pair of
+    # elements will become a key/value pair in the new Catalog. If the source
+    # array has an odd number of elements the last element will be discarded.
+    # If a block is given each element in the source array will be passed to
+    # the block and the result will be stored in the new Catalog.
+    def self.from_array(*args)
+      collected = []
+      data = args.flatten
+
+      max = ((data.size % 2 == 0) ? data.size-1 : data.size-2)
+      (0..max).step(2) do |index|
+        key = block_given? ? yield(data[index]) : data[index]
+        value = block_given? ? yield(data[index+1]) : data[index+1]
+        collected << [key, value]
+      end
+
+      catalog = Catalog.new
+      catalog.instance_variable_set(:@data, collected)
+      return catalog
+    end
+
+    # Creates a new Catalog object from an array of key/value pairs.
+    # Each key/value pair in the source array will be stored in the new
+    # Catalog. If a block is given each value in the from the source array
+    # will be passed to the block and the result will be stored as the
+    # value in the Catalog.
+    def self.from_catalog(data, *args)
+      collected = []
+
+      if args.empty? && data.size == 2 && !data.first.is_a?(Array)
+        # Catalog.from_catalog([:one, 1])
+        data = [data]
+      elsif !args.empty?
+        #Catalog.from_catalog([:one, 1], [:two, 2], [:three, 3])
+        data = [data] + args
+      end
+
+      data.each do |item|
+        if block_given?
+          collected << [item.first, yield(item.last)]
+        else
+          collected << item
+        end
+      end
+      
+      catalog = Catalog.new
+      catalog.instance_variable_set(:@data, collected)
+      return catalog
+    end
+
+    class << self
+      alias :from_catalogue :from_catalog
+    end
+
+    # Returns true if self array contains no elements.
+    def empty?
+      size == 0
+    end
+
+    # Returns the number of elements in self. May be zero.
+    def length
+      @data.length
+    end
+
+    alias :size :length
+
+    # Returns the first element, or the first n elements, of the array.
+    # If the array is empty, the first form returns nil, and the second
+    # form returns an empty array.
+    def first
+      @data.first
+    end
+
+    # Returns the last element(s) of self. If the array is empty,
+    # the first form returns nil.
+    def last
+      @data.last
+    end
+
+    # Equality—Two arrays are equal if they contain the same number of
+    # elements and if each element is equal to (according to Object.==)
+    # the corresponding element in the other array.
+    def ==(other)
+      if other.is_a? Catalog
+        return (@data == other.instance_variable_get(:@data))
+      elsif other.is_a? Array
+        return (@data == other)
+      else
+        return false
+      end
+    end
+
+    alias :eql? :==
+
+    # Comparison—Returns an integer (-1, 0, or +1) if this array is less
+    # than, equal to, or greater than other_ary. Each object in each
+    # array is compared (using <=>). If any value isn’t equal, then that
+    # inequality is the return value. If all the values found are equal,
+    # then the return is based on a comparison of the array lengths. Thus,
+    # two arrays are “equal” according to Array#<=> if and only if they have
+    # the same length and the value of each element is equal to the value of
+    # the corresponding element in the other array.
+    def <=>(other)
+      other = other.instance_variable_get(:@data) if other.is_a?(Catalog)
+      if other.is_a? Array
+        return @data <=> other
+      else
+        raise TypeError.new("can't convert #{other.class} into Catalog")
+      end
+    end
+
+    alias :compare :<=>
+    alias :compare_to :<=>
+
+    # Returns a new array populated with the given objects.
+    def [](index)
+      datum = @data[index]
+      return (datum.nil? ? nil : datum.dup)
+    end
+
+    alias :at :[]
+
+    # Element Assignment—Sets the element at index, or replaces a subarray starting
+    # at start and continuing for length elements, or replaces a subarray specified
+    # by range. If indices are greater than the current capacity of the array, the
+    # array grows automatically. A negative indices will count backward from the end
+    # of the array. Inserts elements if length is zero. An IndexError is raised if a
+    # negative index points past the beginning of the array. See also Array#push,
+    # and Array#unshift.
+    def []=(index, value)
+      if (index >= 0 && index >= @data.size) || (index < 0 && index.abs > @data.size)
+        raise ArgumentError.new('index must reference an existing element')
+      elsif value.is_a?(Hash) && value.size == 1
+        @data[index] = [value.keys.first, value.values.first]
+      elsif value.is_a?(Array) && value.size == 2
+        @data[index] = value.dup
+      else
+        raise ArgumentError.new('value must be a one-element hash or a two-element array')
+      end
+    end
+
+    # Returns a string representation of Catalog.
+    def to_s
+      return @data.to_s
+    end
+
+    # Set Intersection—Returns a new array containing elements common to the two
+    # arrays, with no duplicates.
+    def &(other)
+      other = other.instance_variable_get(:@data) if other.is_a?(Catalog)
+      if other.is_a? Array
+        return Catalog.from_catalog(@data & other)
+      else
+        raise TypeError.new("can't convert #{other.class} into Catalog")
+      end
+    end
+
+    alias :intersection :&
+
+    # Concatenation—Returns a new array built by concatenating the two arrays
+      # together to produce a third array.
+    def +(other)
+      other = other.instance_variable_get(:@data) if other.is_a?(Catalog)
+      if other.is_a? Array
+        return Catalog.from_catalog(@data + other)
+      else
+        raise TypeError.new("can't convert #{other.class} into Catalog")
+      end
+    end
+
+    alias :add :+
+    alias :sum :+
+
+    # Set Union—Returns a new array by joining this array with other_array,
+    # removing duplicates.
+    def |(other)
+      other = other.instance_variable_get(:@data) if other.is_a?(Catalog)
+      if other.is_a? Array
+        return Catalog.from_catalog(@data | other)
+      else
+        raise TypeError.new("can't convert #{other.class} into Catalog")
+      end
+    end
+
+    alias :union :|
+
+    # Append—Pushes the given object(s) on to the end of this array.
+    # This expression returns the array itself, so several appends
+    # may be chained together.
+    def push(item)
+      if item.is_a?(Hash) && item.size == 1
+        @data << [item.keys.first, item.values.first]
+        return self
+      elsif item.is_a?(Array) && item.size == 2
+        @data << item
+        return self
+      else
+        raise TypeError.new("can't convert #{item.class} into Catalog")
+      end
+    end
+
+    alias :<< :push
+    alias :append :push
+
+    # Removes the last element from self and returns it, or nil if the
+    # Catalog is empty.
+    def pop
+      if self.empty?
+        return nil
+      else
+        return @data.pop
+      end
+    end
+
+    # Copies the last element from self and returns it, or nil if the
+    # Catalog is empty.
+    def peek
+      if self.empty?
+        return nil
+      else
+        return @data.last.dup
+      end
+    end
+
+    # Returns a new array populated with the keys from this hash.
+    # See also Hash#values.
+    def keys
+      return @data.collect{|item| item.first}
+    end
+
+    # Returns a new array populated with the values from hsh.
+    # See also Hash#keys.
+    def values
+      return @data.collect{|item| item.last}
+    end
+
+    # Calls block once for each key in hsh, passing the key and value
+    # to the block as a two-element array. Because of the assignment
+    # semantics of block parameters, these elements will be split out
+    # if the block has two formal parameters. Also see Hash.each_pair,
+    # which will be marginally more efficient for blocks with two
+    # parameters.
+    def each(&block)
+      @data.each do |item|
+        yield(item)
+      end
+    end
+
+    # Calls block once for each key in hsh, passing the key and value as parameters.
+    def each_pair(&block)
+      @data.each do |item|
+        yield(item.first, item.last)
+      end
+    end
+
+    # Calls block once for each key in hsh, passing the key as a parameter.
+    def each_key(&block)
+      @data.each do |item|
+        yield(item.first)
+      end
+    end
+
+    # Calls block once for each key in hsh, passing the value as a parameter.
+    def each_value(&block)
+      @data.each do |item|
+        yield(item.last)
+      end
+    end
+
+    # Returns true if the given object is present in self (that is,
+    # if any object == anObject), false otherwise.
+    def include?(key=nil, value=nil)
+      if key && value
+        return @data.include?([key, value])
+      elsif key.is_a?(Array)
+        return @data.include?(key)
+      elsif key.is_a?(Hash) && key.size == 1
+        return @data.include?([key.keys.first, key.values.first])
+      else
+        return false
+      end
+    end
+
+    # Element Reference—Returns the element at index, or returns a
+    # subarray starting at start and continuing for length elements,
+    # or returns a subarray specified by range. Negative indices count
+    # backward from the end of the array (-1 is the last element).
+    # Returns nil if the index (or starting index) are out of range.
+    def slice(index, length=nil)
+      if length.nil?
+        catalog = @data.slice(index)
+      else
+        catalog = @data.slice(index, length)
+      end
+      return Catalog.new(catalog)
+    end
+
+    # Deletes the element(s) given by an index (optionally with a length)
+    # or by a range. Returns the deleted object, subarray, or nil if the
+    # index is out of range.
+    def slice!(index, length=nil)
+      if length.nil?
+        catalog = @data.slice!(index)
+      else
+        catalog = @data.slice!(index, length)
+      end
+      return Catalog.new(catalog)
+    end
+
+    # Return a new Catalog created by sorting self according to the natural
+    # sort order of the keys.
+    def sort_by_key
+      sorted = @data.sort{|a, b| a.first <=> b.first}
+      return Catalog.new(sorted)
+    end
+
+    # Sort self according to the natural sort order of the keys. Returns self.
+    def sort_by_key!
+      sorted = @data.sort!{|a, b| a.first <=> b.first}
+      return self
+    end
+
+    # Return a new Catalog created by sorting self according to the natural
+    # sort order of the values.
+    def sort_by_value
+      sorted = @data.sort{|a, b| a.last <=> b.last}
+      return Catalog.new(sorted)
+    end
+
+    # Sort self according to the natural sort order of the values. Returns self.
+    def sort_by_value!
+      sorted = @data.sort!{|a, b| a.last <=> b.last}
+      return self
+    end
+
+    # Returns a new array created by sorting self. Comparisons for
+    # the sort will be done using the <=> operator or using an
+    # optional code block. The block implements a comparison between
+    # a and b, returning -1, 0, or +1. See also Enumerable#sort_by.
+    def sort(&block)
+      sorted = @data.sort(&block)
+      return Catalog.new(sorted)
+    end
+
+    # Sorts self. Comparisons for the sort will be done using the <=>
+    # operator or using an optional code block. The block implements a
+    # comparison between a and b, returning -1, 0, or +1.
+    # See also Enumerable#sort_by.
+    def sort!(&block)
+      sorted = @data.sort!(&block)
+      return self
+    end
+
+    # Returns a new array that is a one-dimensional flattening of self.
+    def to_a
+      return @data.flatten
+    end
+
+    # Returns a new hash by converting each key/value pair in self into
+    # a key/value pair in the hash. When duplicate keys are encountered
+    # the last value associated with that key is kept and the others are
+    # discarded.
+    def to_hash
+      catalog = {}
+      @data.each do |item|
+        catalog[item.first] = item.last
+      end
+      return catalog
+    end
+
+    # Returns a new array that is the dat equivalent of self where each
+    # key/value pair is an two-element array within the returned array.
+    def to_catalog
+      return @data.dup
+    end
+
+    alias :to_catalogue :to_catalog
+
+    # Deletes items from self that are equal to obj. If the item is
+    # not found, returns nil. If the optional code block is given,
+    # returns the result of block if the item is not found.
+    def delete(key, value=nil)
+      item = nil
+
+      if key && value
+        item = @data.delete([key, value])
+      elsif key.is_a? Array
+        item = @data.delete(key)
+      elsif key.is_a? Hash
+        item = @data.delete([key.keys.first, key.values.first])
+      end
+
+      item = yield if item.nil? && block_given?
+      return item
+    end
+
+    # Deletes the element at the specified index, returning that element,
+    # or nil if the index is out of range. See also Array#slice!.
+    def delete_at(index)
+      item = @data.delete_at(index)
+      item = yield if item.nil? && block_given?
+      return item
+    end
+
+    # Deletes every element of self for which block evaluates to true.
+    def delete_if(&block)
+      raise ArgumentError.new('no block supplied') unless block_given?
+      if block.arity <= 1
+        items = @data.delete_if(&block)
+      else
+        items = []
+        @data.each do |key, value|
+          items << [key, value] if yield(key, value)
+        end
+        items.each {|item| @data.delete(item)}
+      end
+      return self
+    end
+  end
+
+  class Catalogue < Catalog; end
+end