arrayfields 3.6.0 → 3.7.0

data/README

@@ -1,72 +1,181 @@
-URLS:
+NAME
+  arrayfields.rb
 
-  - http://raa.ruby-lang.org/project/arrayfields/
-  - http://www.codeforpeople.com/lib/ruby/arrayfields/
-  - http://rubyforge.org/projects/arrayfields/
-
-SYNOPSIS:
-
-  allow keyword access to arrays:
+URIS
+  http://rubyforge.org/projects/arrayfields/
+  http://www.codeforpeople.com/lib/ruby/arrayfields/
+  http://raa.ruby-lang.org/project/arrayfields/
 
+SYNOPSIS
     require 'arrayfields'  
 
     fields = 'name', 'age'
-    row = [ 'bob', 30 ]
-
-    row.fields = fields
-
-    row[ 'name' ]                #=> 'bob'
-    row.indices 'name', 'age'    #=> [ 'bob', 30 ]
-
-  assigning to un-named fields appends:
-
-    stack = []
-    stack.fields = %w(zero one)            
-    stack['zero'] = 'zero'
-    stack['one'] = 'one'
-    stack                        #=> [ 'zero', 'one' ]
-
-  useful for database work:
-
-    relation = pgconn.query sql
-    relation.size                #=> 65536
-
-    # yikes! do we really want to re-construct a hash for for each tuple when
-    # we already have Arrays?
-
-    fields = %w(ssn name position)
-    table.each{|tuple| tuple.fields = fields}
-
-    tuples[34578]['ssn']         #=> 574865032
-
-LIST OF OVERRIDDEN METHODS:
-  
-  - Array#[]
-  - Array#[]=
-  - Array#at
-  - Array#delete_at
-  - Array#fill
-  - Array#values_at
-  - Array#indices
-  - Array#indexes
-  - Array#slice
-  - Array#slice!
-
-LIST OF NEW Array METHODS:
-
-  - Array#fields=
-  - Array#each_with_field
-
-DOCS/USAGE/SAMPLE:
-
-  - lib/arrayfields.rb
-  - test/arrayfields.rb
-
-AUTHOR:
-
-  ara.t.howard@noaa.gov        
-
-HISTORY:
+    a = [ 'zaphod', 42 ]
+
+    a.fields = fields
+
+    a[ 'name' ]                #=> 'zaphod'
+    a[ :name  ]                #=> 'zaphod'
+    a.indices 'name', 'age'    #=> [ 'zaphod', 42 ]
+
+DESCRIPTION
+  allow keyword access to array instances.  arrayfields works by adding only a
+  few methods to arrays, namely #fields= and fields, but the #fields= method
+  is hooked to extend arrays on a per object basis.  in otherwords __only__
+  those arrays whose fields are set will have auto-magical keyword access
+  bestowed on them - all other arrays remain unaffected.  arrays with keyword
+  access require much less memory when compared to hashes/objects and yet
+  still provide fast lookup.
+
+LIST OF OVERRIDDEN METHODS
+  Array#[]
+  Array#slice
+  Array#[]=
+  Array#at
+  Array#delete_at
+  Array#fill
+  Array#values_at
+  Array#indices
+  Array#indexes
+  Array#slice!
+
+LIST OF HASH-LIKE METHODS
+  Array#each_with_field
+  Array#each_pair
+  Array#each_key
+  Array#each_value
+  Array#fetch
+  Array#has_key?
+  Array#member?
+  Array#key?
+  Array#has_value?
+  Array#value?
+  Array#keys
+  Array#store
+  Array#values
+  Array#to_hash
+  Array#to_h
+  Array#update
+  Array#replace
+  Array#invert
+
+LIST OF ADDED Array METHODS
+  Array#fields=
+  Array#fields
+
+LIST OF ADDED Array CLASS METHODS
+  Array.fields/Array.struct
+
+SAMPLES
+
+  <========< sample/a.rb >========>
+
+  ~ > cat sample/a.rb
+
+    require 'arrayfields'
+    #
+    # the class Array has only a few added method, one is for setting the fields,
+    # when the fields are set for an array THIS INSTANCE ONLY will be modified to
+    # allow keyword access.  other arrays will not be affected!
+    #
+      a = [0,1,2]
+      fields = ['zero', 'one', 'two']
+      a.fields = fields                # ONLY the Array 'a' is affected!
+    #
+    # keyword access is now allowed for many methods
+    #
+      p a['zero']                        #=> 0
+      p a['one']                         #=> 1
+      p a['two']                         #=> 2
+      p a.at('one')                      #=> 1
+      p a.values_at('zero', 'two')       #=> [0, 2]
+    #
+    # assigmnet is allowed
+    #
+      a['zero'] = 42
+      p a['zero']                        #=> 0
+      a['zero'] = 0 
+    #
+    # assignment to non-fields results in the element being appended and the field
+    # being added for future use (also appended)
+    #
+      p(a.fields.join(','))                 #=> "zero, one, two"
+      p a['three']                          #=> nil
+      a['three'] = 3
+      p(a.fields.join(','))                 #=> "zero, one, two, three"
+      p a['three']                          #=> 3 
+    #
+    # other detructive methods are also keyword enabled
+    #
+      a.fill 42, 'zero', len = a.size
+      p(a.values_at(a.fields))              #=> [42, 42, 42, 42]
+      a.replace [0,1,2,3]
+    
+      a.slice! 'two', 2 
+      p a                                   #=> [0,1] 
+
+  ~ > ruby sample/a.rb
+
+    0
+    1
+    2
+    1
+    [0, 2]
+    42
+    "zero,one,two"
+    nil
+    "zero,one,two,three"
+    3
+    [42, 42, 42, 42]
+    [0, 1]
+
+
+  <========< sample/b.rb >========>
+
+  ~ > cat sample/b.rb
+
+    require 'arrayfields'
+    #
+    # the struct/fields factory method can be used in much the same way as ruby's
+    # own struct generators and is useful when the fields for a set of arrays is
+    # known apriori
+    #
+      c = Array.fields :a, :b, :c  # same as Array.struct
+      a = c.new [42, nil, nil]
+      a[:c] = 42
+      p a                          #=> [42, nil, 42]
+    #
+    # of course we can append too
+    #
+      a[:d] = 42.0
+      p a[:d]                      #=> 42.0
+      p a                          #=> [42, nil, 42, 42.0]
+
+  ~ > ruby sample/b.rb
+
+    [42, nil, 42]
+    42.0
+    [42, nil, 42, 42.0]
+
+
+AUTHOR
+  ara.t.howard@gmail.com
+
+HISTORY
+  3.7.0:
+    - cleaned up multiton pattern in ArrayFields::FieldSet
+    - mods for ruby 1.8.6
+    - added PseudoHash class
+    - added Array.struct/fields class generator
+
+  3.6.0:
+    - made string/symbol keys interchangeable
+
+        list = [0, 1, 2]
+        list.fields = %w( a b c )
+        p list['a'] #=> 0
+        p list[:a] #=> 0
+    
 
   3.5.0:
     - added more hash-like methods

data/README.tmpl

@@ -0,0 +1,147 @@
+NAME
+  arrayfields.rb
+
+URIS
+  http://rubyforge.org/projects/arrayfields/
+  http://www.codeforpeople.com/lib/ruby/arrayfields/
+  http://raa.ruby-lang.org/project/arrayfields/
+
+SYNOPSIS
+    require 'arrayfields'  
+
+    fields = 'name', 'age'
+    a = [ 'zaphod', 42 ]
+
+    a.fields = fields
+
+    a[ 'name' ]                #=> 'zaphod'
+    a[ :name  ]                #=> 'zaphod'
+    a.indices 'name', 'age'    #=> [ 'zaphod', 42 ]
+
+DESCRIPTION
+  allow keyword access to array instances.  arrayfields works by adding only a
+  few methods to arrays, namely #fields= and fields, but the #fields= method
+  is hooked to extend arrays on a per object basis.  in otherwords __only__
+  those arrays whose fields are set will have auto-magical keyword access
+  bestowed on them - all other arrays remain unaffected.  arrays with keyword
+  access require much less memory when compared to hashes/objects and yet
+  still provide fast lookup.
+
+LIST OF OVERRIDDEN METHODS
+  Array#[]
+  Array#slice
+  Array#[]=
+  Array#at
+  Array#delete_at
+  Array#fill
+  Array#values_at
+  Array#indices
+  Array#indexes
+  Array#slice!
+
+LIST OF HASH-LIKE METHODS
+  Array#each_with_field
+  Array#each_pair
+  Array#each_key
+  Array#each_value
+  Array#fetch
+  Array#has_key?
+  Array#member?
+  Array#key?
+  Array#has_value?
+  Array#value?
+  Array#keys
+  Array#store
+  Array#values
+  Array#to_hash
+  Array#to_h
+  Array#update
+  Array#replace
+  Array#invert
+
+LIST OF ADDED Array METHODS
+  Array#fields=
+  Array#fields
+
+LIST OF ADDED Array CLASS METHODS
+  Array.fields/Array.struct
+
+SAMPLES
+  @samples
+
+AUTHOR
+  ara.t.howard@gmail.com
+
+HISTORY
+  3.7.0:
+    - multiton pattern clean up, thanks gavin kistner!
+    - mods for ruby 1.8.6 (alias bug in 1.8.6 i think)
+    - added PseudoHash class
+    - added Array.struct/fields class generator
+
+  3.6.0:
+    - made string/symbol keys interchangeable
+
+        list = [0, 1, 2]
+        list.fields = %w( a b c )
+        p list['a'] #=> 0
+        p list[:a] #=> 0
+    
+
+  3.5.0:
+    - added more hash-like methods
+      - update
+      - replace
+      - invert
+
+  3.4.0:
+    - added FieldedArray[] ctor
+    - added methods to make Arrays with fields set behave more closely to Hashes
+      - each_pair 
+      - each_key
+      - each_value
+      - fetch
+      - has_key?
+      - member?
+      - key?
+      - has_value?
+      - value?
+      - keys?
+      - store
+      - values
+
+  3.3.0:
+    - added gemspec file - thnx Assaph Mehr
+    - added FieldedArray proxy class which minimizes modifications to class
+      Array and allow ArrayFields to work (potientially) other arraylike object.
+      thnks Sean O'Dell
+    - added ArrayFields#to_hash method - this seems like an obvious one to add!
+    - remedied bug where using append feature of assigning with unknow field
+      appedended but did not append to acutal fields
+    - added samples
+    - created rubyforge accnt @ http://rubyforge.org/projects/arrayfields/ 
+
+  3.2.0:
+    - precedence fix in many methods - thnx. nobu
+    - test for #slice! were not being run - corrected
+    - added test for appeding via "a['new_field'] = 42"
+
+  3.1.0:
+    - added FieldSet class to reduce ram - thnx. Kirk Haines for profiliing
+      memory and prompting this change
+
+    - interface changed every so slightly so
+
+        a.fields = 'a', 'b', 'c'
+
+      is not allowed.  use
+
+        a.fields = %w(a b c) 
+
+      or
+
+        a.fields = ['a', 'b', 'c']
+
+
+  3.0.0:
+    - added unit tests

data/gemspec.rb

@@ -1,8 +1,10 @@
+
 lib, version = File::basename(File::dirname(File::expand_path(__FILE__))).split %r/-/, 2
 
 require 'rubygems'
 
 Gem::Specification::new do |spec|
+  $VERBOSE = nil
   spec.name = lib 
   spec.version = version 
   spec.platform = Gem::Platform::RUBY
@@ -17,6 +19,8 @@ Gem::Specification::new do |spec|
   spec.has_rdoc = File::exist? "doc" 
   spec.test_suite_file = "test/#{ lib }.rb" if File::directory? "test"
 
+  spec.extensions << "extconf.rb" if File::exists? "extconf.rb"
+
   spec.author = "Ara T. Howard"
   spec.email = "ara.t.howard@noaa.gov"
   spec.homepage = "http://codeforpeople.com/lib/ruby/#{ lib }/"

data/gen_readme.rb

@@ -0,0 +1,32 @@
+require 'pathname'
+
+$VERBOSE=nil
+
+def indent s, n = 2
+  ws = ' ' * n
+  s.gsub %r/^/, ws 
+end
+
+template = IO::read 'README.tmpl'
+
+samples = ''
+prompt = '~ > '
+
+Dir['sample*/*'].sort.each do |sample|
+  samples << "\n" << "  <========< #{ sample } >========>" << "\n\n"
+
+  cmd = "cat #{ sample }" 
+  samples << indent(prompt + cmd, 2) << "\n\n" 
+  samples << indent(`#{ cmd }`, 4) << "\n" 
+
+  cmd = "ruby #{ sample }" 
+  samples << indent(prompt + cmd, 2) << "\n\n" 
+
+  cmd = "ruby -Ilib #{ sample }" 
+  samples << indent(`#{ cmd } 2>&1`, 4) << "\n" 
+end
+
+#samples.gsub! %r/^/, '  '
+
+readme  = template.gsub %r/^\s*@samples\s*$/, samples
+print readme 

data/lib/{arrayfields-3.6.0.rb → arrayfields-3.7.0.rb}

@@ -1,35 +1,30 @@
 #
 # The ArrayFields module implements methods which allow an Array to be indexed
-# by String or Symbol. It is not required to manually use this module to extend
-# Array's - they are auto-extended when Array#fields= is called
+# by String or Symbol. It is not required to manually use this module to
+# extend Arrays - they are auto-extended on a per-object basis when
+# Array#fields= is called
 #
   module ArrayFields 
-#{{{
-    VERSION = '3.6.0'
+    VERSION = '3.7.0' unless defined? VERSION
+    def self.version() VERSION end
   #
   # multiton cache of fields - wraps fields and fieldpos map to save memory
   #
     class FieldSet
-#{{{
       class << self
-#{{{
         def new fields
-#{{{
-          @sets ||= {}
-          obj = @sets[fields]
-          unless obj
-            obj = super  
-            @sets[fields] = obj
-          end
-          obj
-#}}}
+          @sets[fields] ||= super
+        end
+        def init_sets
+          @sets = {}
         end
-#}}}
       end
+
+      init_sets
+
       attr :fields
       attr :fieldpos
       def initialize fields
-#{{{
         raise ArgumentError, "<#{ fields.inspect }> not inject-able" unless
           fields.respond_to? :inject
 
@@ -43,25 +38,20 @@
           end
 
         @fields = fields
-#}}}
       end
       def pos f
-#{{{
         return @fieldpos[f] if @fieldpos.has_key? f 
         f = f.to_s
         return @fieldpos[f] if @fieldpos.has_key? f 
         f = f.intern
         return @fieldpos[f] if @fieldpos.has_key? f 
         nil
-#}}}
       end
-#}}}
     end
   #
   # methods redefined to work with fields as well as numeric indexes
   #
-    def [](idx, *args) 
-#{{{
+    def [] idx, *args
       if @fieldset and (String === idx or Symbol === idx)
         pos = @fieldset.pos idx
         return nil unless pos
@@ -69,11 +59,18 @@
       else
         super
       end
-#}}}
     end
-    alias slice []
+    def slice idx, *args
+      if @fieldset and (String === idx or Symbol === idx)
+        pos = @fieldset.pos idx
+        return nil unless pos
+        super(pos, *args)
+      else
+        super
+      end
+    end
+
     def []=(idx, *args) 
-#{{{
       if @fieldset and (String === idx or Symbol === idx) 
         pos = @fieldset.pos idx
         unless pos
@@ -84,10 +81,8 @@
       else
         super
       end
-#}}}
     end
     def at idx
-#{{{
       if @fieldset and (String === idx or Symbol === idx)
         pos = @fieldset.pos idx
         return nil unless pos
@@ -95,10 +90,8 @@
       else
         super
       end
-#}}}
     end
     def delete_at idx
-#{{{
       if @fieldset and (String === idx or Symbol === idx)
         pos = @fieldset.pos idx
         return nil unless pos
@@ -106,10 +99,8 @@
       else
         super
       end
-#}}}
     end
     def fill(obj, *args)
-#{{{
       idx = args.first
       if idx and @fieldset and (String === idx or Symbol === idx)
         idx = args.shift
@@ -118,67 +109,69 @@
       else
         super
       end
-#}}}
     end
+
     def values_at(*idxs)
-#{{{
       idxs.flatten!
       if @fieldset
         idxs.map!{|i| (String === i or Symbol === i) ? @fieldset.pos(i) : i}
       end
       super(*idxs)
-#}}}
     end
-    alias indices values_at
-    alias indexes values_at 
+    def indices(*idxs)
+      idxs.flatten!
+      if @fieldset
+        idxs.map!{|i| (String === i or Symbol === i) ? @fieldset.pos(i) : i}
+      end
+      super(*idxs)
+    end
+    def indexes(*idxs)
+      idxs.flatten!
+      if @fieldset
+        idxs.map!{|i| (String === i or Symbol === i) ? @fieldset.pos(i) : i}
+      end
+      super(*idxs)
+    end
+
     def slice!(*args)
-#{{{
       ret = self[*args]
       self[*args] = nil
       ret
-#}}}
     end
     def each_with_field
-#{{{
       each_with_index do |elem, i|
         yield elem, @fieldset.fields[i]
       end
-#}}}
     end
   #
   # methods which give a hash-like interface 
   #
     def each_pair
-#{{{
       each_with_index do |elem, i|
         yield @fieldset.fields[i], elem
       end
-#}}}
     end
     def each_key
-#{{{
       @fieldset.each{|field| yield field}
-#}}}
     end
     def each_value(*args, &block)
-#{{{
       each(*args, &block)
-#}}}
     end
     def fetch key
-#{{{
       self[key] or raise IndexError, 'key not found'
-#}}}
     end
+
     def has_key? key
-#{{{
       @fieldset.fields.include? key
-#}}}
     end
-    alias member? has_key?
-    alias key? has_key?
+    def member? key
+      @fieldset.fields.include? key
+    end
+    def key? key
+      @fieldset.fields.include? key
+    end
+
     def has_value? value
-#{{{
       if respond_to? 'include?'
         self.include? value
       else
@@ -186,21 +179,24 @@
         each{|val| a << val}
         a.include? value
       end
-#}}}
     end
-    alias value? has_value?
+    def value? value
+      if respond_to? 'include?'
+        self.include? value
+      else
+        a = []
+        each{|val| a << val}
+        a.include? value
+      end
+    end
+
     def keys
-#{{{
       fields
-#}}}
     end
     def store key, value
-#{{{
       self[key] = value
-#}}}
     end
     def values
-#{{{
       if respond_to? 'to_ary'
         self.to_ary
       else
@@ -208,10 +204,9 @@
         each{|val| a << val}
         a
       end
-#}}}
     end
+
     def to_hash
-#{{{
       if respond_to? 'to_ary'
         h = {}
         @fieldset.fields.zip(to_ary){|f,e| h[f] = e}
@@ -223,39 +218,42 @@
         @fieldset.fields.zip(a){|f,e| h[f] = e}
         h
       end
-#}}}
     end
-    alias to_h to_hash
+    def to_h
+      if respond_to? 'to_ary'
+        h = {}
+        @fieldset.fields.zip(to_ary){|f,e| h[f] = e}
+        h
+      else
+        a = []
+        each{|val| a << val}
+        h = {}
+        @fieldset.fields.zip(a){|f,e| h[f] = e}
+        h
+      end
+    end
+
     def update other
-#--{{{
       other.each{|k,v| self[k] = v}
       to_hash
-#--}}}
     end
     def replace other
-#--{{{
       Hash === other ? update(other) : super
-#--}}}
     end
     def invert
-#--{{{
       to_hash.invert
-#--}}}
     end
-#}}}
   end
 #
 # Fieldable encapsulates methods in common for classes which may have their
-# fields set
+# fields set and subsequently be auto-extended by ArrayFields
 #
   module Fieldable
-#{{{
   #
   # sets fields an dynamically extends this Array instance with methods for
   # keyword access
   #
     def fields= fields
-#{{{
       extend ArrayFields unless defined? @fieldset 
 
       @fieldset = 
@@ -264,7 +262,6 @@
         else
           ArrayFields::FieldSet.new fields
         end
-#}}}
     end
   #
   # access to fieldset
@@ -274,19 +271,32 @@
   # access to field list
   #
     def fields
-#{{{
       @fieldset and @fieldset.fields
-#}}}
     end
-#}}}
   end
 #
-# The Array class is extened with a methods to allow keyword access 
+# Array instances are extened with two methods only: Fieldable#fields= and
+# Fieldable#fields.  only when Fieldable#fields= is called will the full set
+# of ArrayFields methods auto-extend the Array instance.  the Array class also
+# has added a class generator when the fields are known apriori.
 #
   class Array
-#{{{
     include Fieldable
-#}}}
+
+    class << self
+      def fields *fields
+        Class.new(self) do
+          const_set :FIELDS, ArrayFields::FieldSet.new(fields.flatten)
+          include ArrayFields
+          def initialize *a, &b
+            super
+          ensure
+            @fieldset = self.class.const_get :FIELDS
+          end
+        end
+      end
+      alias_method 'struct', 'fields'
+    end
   end
 #
 # proxy class that allows an array to be wrapped in a way that still allows #
@@ -300,48 +310,59 @@
 #
 #
   class FieldedArray
-#{{{
     include Fieldable
     class << self
-
       def [](*pairs)
-#{{{
         pairs.flatten!
-        raise ArgumentError, "argument must be key/val paris" unless 
+        raise ArgumentError, "argument must be key/val pairs" unless 
           (pairs.size % 2 == 0 and pairs.size >= 2)
         fields, elements = [], []
-        #pairs.each do |f,e| 
         while((f = pairs.shift) and (e = pairs.shift)) 
-          raise ArgumentError, "field must be String or Symbol" unless
-            (String === f or Symbol === f)
           fields << f and elements << e
         end
         new fields, elements
-#}}}
       end
-
     end
-    def initialize fields, array
-#{{{
+    def initialize fields = [], array = []
       @a = array
       self.fields = fields
-#}}}
     end
     def method_missing(meth, *args, &block)
-#{{{
       @a.send(meth, *args, &block)
-#}}}
     end
     delegates =
-#{{{
       %w(
         to_s
         to_str
         inspect
       )
-#}}}
     delegates.each do |meth| 
       class_eval "def #{ meth }(*a,&b); @a.#{ meth }(*a,&b);end"
     end
-#}}}
+  end
+
+  class PseudoHash < ::Array
+    class << self
+      def [](*pairs)
+        pairs.flatten!
+        raise ArgumentError, "argument must be key/val pairs" unless 
+          (pairs.size % 2 == 0 and pairs.size >= 2)
+        keys, values = [], []
+        while((k = pairs.shift) and (v = pairs.shift)) 
+          keys << k and values << v
+        end
+        new keys, values
+      end
+    end
+    def initialize keys = [], values = []
+      self.replace values
+      self.fields = keys
+    end
+    def to_yaml opts = {}
+      YAML::quick_emit object_id, opts do |out|
+        out.map taguri, to_yaml_style do |map|
+          each_pair{|f,v| map.add f,v}
+        end
+      end
+   end 
   end