super_map 1.0.0

data/README

@@ -0,0 +1,91 @@
+Introduction
+============
+
+SuperMap is a two-way, multi-purpose ordered hash with some additional
+capabilities (additional attributes, translations). It is meant to be used with
+Rails, but it doesn't depend on them, so someone might find it useful in other
+environments.
+
+Ever had an enumerable field in a model that would map to a select box in a
+form? Wanted some nice way to operate it as symbol in the code, integer in
+database and label in views? That's where SuperMap comes into play.
+
+Example
+=======
+
+Let's say there is a Payment model with two enumerable fields:
+- payment_type: Cash In, Cash Out, Bonus, Commission
+- payment_method: Paypal, Bank Transfer, Manual
+
+We define 2 SuperMaps:
+
+	class Payment
+
+		PAYMENT_TYPES = SuperMap.new(
+				[:cash_in, 1, { :label => "Cash In", :tax => 0.01 }],
+				[:cash_out, 2, { :label => "Cash Out", :tax => 0.02 }],
+				[:bonus, 123, { :label => "Bonus Payment", :tax => 0.03 }],
+				[:commission, 384728, { :tax => 0.01 }]
+			)
+
+		PAYMENT_METHODS = SuperMap.new(
+				[:paypal, 1, { :label => "Paid via Paypal", :favorite => true }],
+				[:bank_transfer, 2],
+				[:manual, 3],
+				:translation_scope => "activerecord.models.payment.payment_methods"
+			)
+
+	end
+
+PAYMENT_TYPES defines options for payment_type field. Some labels are set
+explicitly, for other options key.titleize will be used implicitly. We also
+defined a custom attribute :tax, which can be accessed using SuperMap#attribute
+method.
+
+PAYMENT_METHODS define translation_scope, which means labels will be present in
+translations file (I18n). :paypal will have custom label, which overrides
+translations.
+
+We can than use those SuperMaps to handle attributes for Payment instances:
+	
+	payment = Payment.new( :payment_method => 1 )
+	payment.payment_type = PAYMENT_TYPES[:cash_out]			# Set to 2
+	label = PAYMENT_TYPES.label( payment.payment_type ) # "Cash Out"
+	label = PAYMENT_TYPES.label( :bonus )								# "Bonus Payment"
+	value = PAYMENT_METHODS[payment.payment_method]			# 1
+	tax = PAYMENT_TYPES.attribute( payment.payment_type, :tax ) # 0.02
+	tax = PAYMENT_TYPES.attribute( :bonus, :tax ) # 0.03
+
+We can also use
+
+	PAYMENT_TYPES.labeled_values
+
+to get the form directly suitable to pass options to f.select helper method.
+
+
+
+To make things even simpler, we can use super_mapped_attr:
+
+	class Payment
+		... # SuperMaps declarations
+
+		super_mapped_attr :payment_type, PAYMENT_TYPES
+		super_mapped_attr :payment_method, PAYMENT_METHODS
+
+	end
+
+Now a whole lot of new methods comes into play:
+
+	p = Payment.new( :payment_method => 1 )
+	p.payment_method_label                      # "Paid via Paypal"
+	p.payment_method_key												# :paypal
+	p.payment_method_attr( :favorite )					# true
+	p.payment_method_key = :manual
+	p.payment_method														# 3
+
+Thanks
+======
+
+Many thanks go to Stefan Nothegger and Sharewise project
+(http://www.sharewise.com), where the original idea and large parts of the code
+originate from.

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+PKG_FILES = FileList[
+  '[a-zA-Z]*',
+  'generators/**/*',
+  'lib/**/*',
+  'rails/**/*',
+  'tasks/**/*',
+  'test/**/*'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name = "super_map"
+  s.version = "1.0.0"
+  s.author = "Marek Janukowicz"
+  s.email = "marek@janukowicz.net"
+  s.homepage = ""
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Swiss army knife of enum-based attributes"
+  s.files = PKG_FILES.to_a
+  s.require_path = "lib"
+  s.has_rdoc = false
+  s.extra_rdoc_files = ["README"]
+	s.add_dependency "i18n", ">= 0.4.0"
+end
+
+desc 'Create gem'
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc 'Run tests'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate RDoc documentation'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SuperMap'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/lib/string_extensions.rb

@@ -0,0 +1,18 @@
+class String
+  
+  # Some poor man's implementations of Rails String extensions in case we can't
+  # use those
+  
+  unless method_defined?( :pluralize )
+    def pluralize
+      [-1,1] == "s" ? self : self + "s"
+    end
+  end
+
+  unless method_defined?( :titleize )
+    def titleize
+      gsub( "_", " " ).capitalize
+    end
+  end
+
+end

data/lib/super_map.rb

@@ -0,0 +1,240 @@
+begin
+  require 'i18n'
+rescue LoadError
+  nil # We don't really need I18n, but if it's not present, :translation_scope can't be used
+end
+require 'string_extensions'
+require 'super_mapped_attr'
+
+# Two-way hash with additional custom data, autogenerated labels and human
+# readable strings - swiss army knife of collections :) Especially suited for
+# emulating enumerable fields in database.
+#
+# Immutable objects - most element accessing methods are cached, there is no
+# designed way to get "raw" elements. If you need another (similar) SuperMap,
+# use +/- methods to get a new one. The methods accessing Element objects
+# directly (each, first, last) should be used with awareness of aforementioned
+# limitations. Usually (when not enumerating over all elements) you would use 
+# key/value/attribute etc. accessing methods, eg. map.key( value ), map.value(
+# key ), map.attribute( key, attr_name ).
+class SuperMap
+
+  include Enumerable
+
+  class Error < ::StandardError; end
+  class UnknownKey < Error; end
+  class UnknownValue < Error; end
+
+  attr_reader :options
+
+  # Map element. Rarely used directly, usually the map object itself is queried
+  # for element properties.
+  class Element
+
+    # Key (symbol) - used for getting element by symbolic name
+    attr_reader :key
+    # Value - corresponds to key, usually an integer or string to be stored in
+    # database
+    attr_reader :value
+    # Additional information about element, eg. time frame, additional
+    # attributes. Also contains the label if not default or provided by I18n.
+    # Takes the form of a Hash.
+    attr_reader :attributes
+
+    # Creates new list element.
+    def initialize( list, key, value, attributes = {} )
+      raise "Key must be a Symbol" unless key.is_a? Symbol
+      raise "Value must NOT be a Symbol" if value.is_a? Symbol
+      @list, @key, @value, @attributes = list, key, value, attributes
+    end
+
+    def label
+      translated_attribute( :label )
+    end
+
+    def description
+      translated_attribute( :description )
+    end
+
+    def method_missing( name, *args )
+      return @attributes[name] || super( name, *args )
+    end
+
+    # Returns all initializing arguments as passed to SuperMap constructor - this
+    # method is used for cloning to another SuperMap.
+    def to_a
+      [key, value, attributes]
+    end
+
+    protected
+    def translated_attribute( attr )
+      return @attributes[attr.to_sym] if @attributes[attr.to_sym]
+      if @list.options[:translation_scope]
+        return I18n.t( @key, :scope => [@list.options[:translation_scope], attr.to_s.pluralize], :default => @key.to_s.titleize )
+      else
+        return @key.to_s.titleize
+      end
+    end
+  end
+
+  # Creates new list.
+  # Elements - arrays with arguments for Element.new (key, value, attributes)
+  # Options (optional last argument): 
+  #   :translation_scope - where to find translated labels/descriptions
+  #   :unknown_value_fatal - whether to raise an exception when accessing
+  #     objects via unknown value (unknown key is always fatal)
+  #
+  # Example:
+  #
+  # class User
+  #   KINDS = SuperMap.new(
+  #     [:member, 1, "Casual member", { :min_age => 18.years, :welcome_string => "Welcome member!" }],
+  #     [:admin, 2, "Administrator", { :min_age => nil, :welcome_string => "Hello admin!" }],
+  #     :translation_scope => "user.kinds"
+  #   )
+  # end
+  # TODO: enforce key/value uniqueness
+  def initialize( *elements )
+    if elements.last.is_a?( Hash )
+      @options = elements.pop
+    else
+      @options = {}
+    end
+    # TODO: handle old syntax here (elements passed in an Array and not as
+    # separate arguments)
+    @elements = elements.collect { |elem| Element.new( *([self] + elem) ) }
+    # We store elements in 2 Hashes, because we need to be able to lookup both
+    # on key (when in need of value) and on value (when in need of a key/label
+    # corresponding to the value fetched from database)
+    @elements_by_key = @elements.inject( {} ) { |hash, elem| hash[elem.key] = elem; hash }
+    @elements_by_value = @elements.inject( {} ) { |hash, elem| hash[elem.value] = elem; hash }
+  end
+
+  # Elements in the form of array (original form as passed as argument)
+  def element_array
+    @element_array ||= @elements.collect { |elem| elem.to_a }
+  end
+
+  # Iterates over the list return Element objects - required for Enumerable
+  # methods to work.
+  def each
+    @elements.each { |elem| yield elem }
+  end
+
+  def first
+    @elements.first
+  end
+
+  def last
+    @elements.last
+  end
+
+  # Removes element(s) corresponding to key(s) (returns new map)
+  # TODO: this should also handle another map as argument
+  def - (*keys)
+    keys = keys.flatten
+    new_elements = select { |el| !keys.include?( el.key ) }.collect { |elem| elem.to_a }
+    return self.class.new( *(new_elements + [@options]) )
+  end
+
+  # Adds elements from another map or array (returns new map)
+  def + (map_or_array)
+    if map_or_array.is_a?( self.class ) # Map
+      return self.class.new( *(element_array + map_or_array.element_array + [@options]) )
+    else # Array
+      return self.class.new( *(element_array + map_or_array + [@options]) )
+    end
+  end
+
+  # Returns array of label/value pairs, useful for SELECT tags - eg. 
+  # f.select( :kind, User::KINDS.labeled_values )
+  def labeled_values
+    @labeled_values ||= @elements.collect { |elem| [elem.label, elem.value] }
+  end
+
+  # Array of values
+  def values
+    @values ||= @elements.collect { |elem| elem.value }
+  end
+
+  # Array of keys
+  def keys
+    @keys ||= @elements.collect { |elem| elem.key }
+  end
+
+  # Number of elements
+  def size
+    @size ||= @elements.size
+  end
+
+  # Key for given value - raises exception on unknown value depending on
+  # :unknown_value_fatal setting
+  def key(value)
+    elem = element_by_value_or_key( value )
+    # Exception handling in element_by_value_or_key
+    return elem ? elem.key : nil
+  end
+
+  # Value for given key - raises exception when key does not exist (to avoid bogus
+  # error messages when called with non-existant key)
+  def value(key)
+    # Exception handling in element_by_value_or_key
+    element_by_value_or_key( key ).value
+  end
+
+  # Label for given value or key (it is determined basing on argument type -
+  # keys must be Symbols while values can not)
+  def label( value_or_key )
+    elem = element_by_value_or_key( value_or_key )
+    return elem ? elem.label : nil
+  end
+
+  # Attribute field for given value or key
+  def attribute(value_or_key, attr_key)
+    elem = element_by_value_or_key( value_or_key )
+    if elem
+      return elem.attributes[attr_key]
+    else
+      return nil
+    end
+  end
+
+  # Returns true if given key exists
+  def has_key?( key )
+    @elements_by_key.has_key?( key )
+  end
+
+  # Returns true if given value exists
+  def has_value?( value )
+    @elements_by_value.has_key?( value )
+  end
+
+  # Returns true if given key (Symbol) or value (non-Symbol) exists
+  def include?( value_or_key )
+    return has_key?( value_or_key ) || has_value?( value_or_key )
+  end
+
+  alias_method '[]', :value
+
+  def element_by_value_or_key( value_or_key )
+   
+    if value_or_key.is_a?( Symbol ) # Key
+      elem = @elements_by_key[value_or_key]
+      if elem
+        return elem
+      else
+        raise UnknownKey, "Unknown key #{value_or_key}"
+      end
+    else
+      elem = @elements_by_value[value_or_key]
+      return elem if elem
+      if @options[:unknown_value_fatal]
+        raise UnknownValue, "Unknown value #{value_or_key}"
+      else
+        return nil
+      end
+    end
+      
+  end
+
+end

data/lib/super_mapped_attr.rb

@@ -0,0 +1,65 @@
+module SuperMappedAttr
+
+  def self.included( klass )
+    klass.extend( ClassMethods )
+  end
+
+  module ClassMethods
+
+    # Makes the attribute mapped by a SuperMap, eg.
+    # class User
+    #
+    #   super_mapped_attr :kind, SuperMap.new(
+    #     [:member, 1, "Casual member", { :min_age => 18.years, :welcome_string => "Welcome member!" }],
+    #     [:admin, 2, "Administrator", { :min_age => nil, :welcome_string => "Hello admin!" }]
+    #   )
+    #
+    # end
+    #
+    # u = User.new( :kind => 1 )
+    #
+    # u.kind_label # "Casual member"
+    #
+    # u.kind_key # :member
+    #
+    # u.kind_attr( :member, :min_age ) # 18.years
+    #
+    # u.kind_key = :admin
+    #
+    # u.kind # 2
+    #
+    # User.kinds # #SuperMap:0x....
+    def super_mapped_attr( attr, map, options = {} )
+
+      if respond_to?( :validates_inclusion_of )
+        validates_inclusion_of attr, { :in => map.values }.merge( options )
+      end
+
+      define_method( "#{attr}_key" ) do
+        map.key(send(attr))
+      end
+
+      define_method( "#{attr}_key=" ) do |key|
+        send( "#{attr}=", map.value( key ))
+      end
+
+      define_method( "#{attr}_label" ) do
+        map.label(send(attr))
+      end
+
+      define_method( "#{attr}_attr" ) do |key|
+        map.attribute(send(attr), key)
+      end
+
+      (class << self; self; end).instance_eval do
+        define_method attr.to_s.pluralize, lambda { map }
+      end
+
+    end
+  end
+end
+
+# Include in ActiveRecord models by default
+if defined?( ActiveRecord::Base )
+  ActiveRecord::Base.send( :include, SuperMappedAttr )
+end

data/test/en.yml

@@ -0,0 +1,9 @@
+en:
+  enum:
+    map:
+      labels:
+        one: NEVER DISPLAY
+        two: Two label
+      descriptions:
+        one: NEVER DISPLAY
+        two: Two description

data/test/super_map_test.rb

@@ -0,0 +1,144 @@
+require 'test/unit'
+require 'super_map'
+I18n.load_path << File.join( File.dirname( __FILE__ ), "en.yml" )
+
+class SuperMapTest < Test::Unit::TestCase
+
+  def setup
+    @color_map = SuperMap.new(
+      [:red, 5, { :rgb => "AA0000", :priority => 3 }],
+      [:green, 2, { :rgb => "00AA00", :priority => 12 }],
+      [:blue, 123, { :rgb => "0000AA", :preference => 8823 }],
+      :translation_scope => "color.map"
+    )
+  end
+
+  def test_element_label_and_description
+    enum_map = SuperMap.new(
+      [:one, 1, { :label => "One label", :description => "One description" }],
+      [:two, 2],
+      :translation_scope => "enum.map"
+    )
+    assert_equal 'One label', enum_map.first.label
+    assert_equal 'One description', enum_map.first.description
+    assert_equal 'Two label', enum_map.last.label
+    assert_equal 'Two description', enum_map.last.description
+  end
+
+  def test_element_attributes
+    red = @color_map.first
+    assert_equal "AA0000", red.rgb
+    assert_equal 3, red.priority
+    blue = @color_map.last
+    assert_equal "0000AA", blue.rgb
+    assert_equal 8823, blue.preference
+  end
+
+  def test_enumeration
+    keys = []
+    @color_map.each do |elem|
+      keys << elem.key
+    end
+    assert_equal [:red, :green, :blue], keys
+    elems = @color_map.select { |elem| elem.value < 10 }.collect { |elem| elem.key }
+    assert_equal [:red, :green], elems
+    elems = @color_map.sort_by { |elem| elem.value }.collect { |elem| elem.key }
+    assert_equal [:green, :red, :blue], elems
+    assert_equal :red, @color_map.first.key
+    assert_equal :blue, @color_map.last.key
+  end
+
+  def test_subtraction
+    # Existing key
+    map = @color_map - :red
+    assert_equal [:green, :blue], map.keys
+    # Non-existant key
+    map = @color_map - :yellow
+    assert_equal [:red, :green, :blue], map.keys
+    # multiple keys
+    map = @color_map - [:green, :blue]
+    assert_equal [:red], map.keys
+    assert_equal @color_map.options[:translation_scope], map.options[:translation_scope]
+  end
+
+  def test_addition
+    # Single element
+    map = @color_map + [[:yellow, 3]]
+    assert_equal [:red, :green, :blue, :yellow], map.keys
+    # Multiple elements
+    map = @color_map + [[:yellow, 3], [:brown, 4]]
+    assert_equal [:red, :green, :blue, :yellow, :brown], map.keys
+    # Add another SuperMap
+    second_map = SuperMap.new( [:yellow, 3], [:brown, 4, {:label => "Blah"}], :translation_scope => "another.scope" )
+    map = @color_map + second_map
+    assert_equal [:red, :green, :blue, :yellow, :brown], map.keys
+    assert_equal @color_map.options[:translation_scope], map.options[:translation_scope]
+    # Original array is untouched
+    assert_equal [:red, :green, :blue], @color_map.keys
+  end
+
+  def test_labeled_values
+    assert_equal [["Red", 5], ["Green", 2], ["Blue", 123]], @color_map.labeled_values
+  end
+
+  def test_values
+    assert_equal [5,2,123], @color_map.values
+  end
+
+  def test_keys
+    assert_equal [:red, :green, :blue], @color_map.keys
+  end
+
+  def test_size
+    assert_equal 3, @color_map.size
+  end
+
+  def test_key
+    assert_equal :red, @color_map.key( 5 )
+    assert_equal :green, @color_map.key( 2 )
+    assert_nil @color_map.key( 3 )
+    @color_map.options[:unknown_value_fatal] = true
+    assert_raise( SuperMap::UnknownValue ) { @color_map.key( 3 ) }
+  end
+
+  def test_value
+    assert_equal 5, @color_map.value( :red )
+    assert_equal 123, @color_map.value( :blue )
+    assert_raise( SuperMap::UnknownKey ) { @color_map.value( :yellow ) }
+  end
+
+  def test_label
+    assert_equal "Blue", @color_map.label( :blue )
+    assert_equal "Red", @color_map.label( 5 )
+  end
+
+  def test_attribute
+    assert_equal 8823, @color_map.attribute( :blue, :preference )
+    assert_equal nil, @color_map.attribute( :blue, :priority ) # This attribute doesn't exist for this element
+    assert_equal 3, @color_map.attribute( :red, :priority )
+  end
+
+  def test_has_key
+    assert @color_map.has_key?( :green )
+    assert !@color_map.has_key?( :yellow )
+  end
+
+  def test_has_value
+    assert @color_map.has_value?( 2 )
+    assert !@color_map.has_value?( 55 )
+  end
+
+  def test_include
+    assert @color_map.include?( :blue )
+    assert !@color_map.include?( :yellow )
+    assert @color_map.include?( 123 )
+    assert !@color_map.include?( 122 )
+  end
+
+  # [] is an alias to #value
+  def test_brackets
+    assert_equal 5, @color_map[ :red ]
+    assert_equal 123, @color_map[ :blue ]
+    assert_raise( SuperMap::UnknownKey ) { @color_map[ :yellow ] }
+  end
+end

data/test/super_mapped_attr_test.rb

@@ -0,0 +1,52 @@
+require 'test/unit'
+require 'super_map'
+I18n.load_path << File.join( File.dirname( __FILE__ ), "en.yml" )
+
+class SuperMappedAttrTest < Test::Unit::TestCase
+
+  class User
+
+    include SuperMappedAttr
+
+    attr_accessor :color
+    super_mapped_attr :color, SuperMap.new(
+      [:red, 5, { :rgb => "AA0000", :priority => 3 }],
+      [:green, 2, { :rgb => "00AA00", :priority => 12 }],
+      [:blue, 123, { :rgb => "0000AA", :preference => 8823 }],
+      :translation_scope => "color.map"
+    )
+
+  end
+
+  def setup
+    @user = User.new
+  end
+
+  def test_label
+    @user.color_key = :red
+    assert_equal "Red", @user.color_label
+    assert_raise( SuperMap::UnknownKey ) do
+      @user.color_key = :asdjfkajf
+    end
+  end
+
+  def test_key
+    # This test DOES make sense - color_key getter and setter both pass through
+    # underlying SuperMap
+    @user.color_key = :red
+    assert_equal :red, @user.color_key
+  end
+
+  def test_attr
+    @user.color_key = :blue
+    assert_nil @user.color_attr( :priority )
+    assert_equal "0000AA", @user.color_attr( :rgb )
+  end
+
+  def test_map_accessor
+    assert_equal "Green", User.colors.label( :green )
+    assert_equal 123, User.colors[ :blue ]
+    assert_equal 12, User.colors.attribute( :green, :priority )
+  end
+
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: super_map
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Marek Janukowicz
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-08 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: i18n
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 0
+        - 4
+        - 0
+        version: 0.4.0
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: marek@janukowicz.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- Rakefile
+- README
+- lib/super_map.rb
+- lib/super_mapped_attr.rb
+- lib/string_extensions.rb
+- test/super_mapped_attr_test.rb
+- test/en.yml
+- test/super_map_test.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Swiss army knife of enum-based attributes
+test_files: []
+