ruby_enum 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88208684028da60b266f75674a01986da03faff7
-  data.tar.gz: da4214d467a22efce5178fcf838b7001209841ba
+  metadata.gz: 113d01a02e7c03f45bfd760a6b6c531f9a63011d
+  data.tar.gz: 9f2d6107d1279bbbfaa0b2fd374bca2bf764a1e4
 SHA512:
-  metadata.gz: fcdfc3364540ee74a798f98639525b13a433386ca2d3393e37720b2857105476edcfac97eab538415a79fc2442ce23c63bee01a39a64eef076d9dd1e73e50d5d
-  data.tar.gz: 57ef03195f5a6ccf80c3379d55d1709002e779e80ad2ade438bfea2360279c36b1c47a139205593e2e73832a7696ef5309c181a933f1658f362741d03de1109f
+  metadata.gz: 21714b280c186a89e71fecac56bac2527b0ff9b3c41325c19915f0f5be692cd8de2c6b2361ccfa8868ddbcacc264b0980d5b0898ffa4a9d24b858d7a84676dcb
+  data.tar.gz: 1cc669a45f6e49df3734dfaff82d83085e70b77d40b1b96965f2ade6a2bf90097888d1ba836e02a6628cba292a06806202839672dc26a3fbf3c6f38d0b9e3ae2

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.1
+  - 2.2.2
+script: bundle exec rspec spec
+branches:
+  only:
+    - master

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_enum (0.4.0)
+    ruby_enum (0.4.1)
 
 GEM
   remote: https://rubygems.org/
@@ -30,3 +30,6 @@ DEPENDENCIES
   rake (~> 10.0)
   rspec (~> 3.3.0)
   ruby_enum!
+
+BUNDLED WITH
+   1.10.6

data/README.md

@@ -1,3 +1,6 @@
+[![Gem
+Version](https://badge.fury.io/rb/ruby_enum.svg)](https://badge.fury.io/rb/ruby_enum)
+
 # RubyEnum
 
 A simple enumeration type for ruby.
@@ -20,55 +23,161 @@ Or install it yourself as:
 
 ## Usage
 
-To create an enumeration type simply include the `RubyEnum` module in your
-enumeration class and provide the enumeration's values as follows:
+To create an enumeration type include the `RubyEnum` module in your enumeration
+class and provide the enumeration's values as follows:
+
 ```ruby
-class Coordinates
+class Coordinate
   include RubyEnum
   
   enum :north
   enum :south
   enum :west
   enum :east
+end
 ```
+Note that you can't define the same enumeration instance twice. An error will
+be raised in this case, for example:
 
-Including `RubyEnum` in any class will make it a singleton. This means that you
-can't create new instances of your class using `new`, `allocate`, `clone` or
-`dup`. You can access an enumeration's value instances in three different ways:
-
-1. Using a class method that matches the provided name of the enumeration
-value:
 ```ruby
-north = Coordinates.north
+class InvalidEnumeration
+  include RubyEnum
+
+  enum :value
+  enum :value
+end
 ```
 
-2. Using a constant:
+Including `RubyEnum` in any class will make it a singleton. You will not be able
+to create new instances of your class using `new`, `allocate`, `clone` or
+`dup`. You can access an enumeration's values in three different ways:
+
+Using a class method that matches the enumeration instance name:
+
 ```ruby
-north = Coordinates::NORTH
+north = Coordinate.north
 ```
 
-3. Treating your enumeration class as a dictionary:
+Using a constant that matches the enumeration instance name:
+
 ```ruby
-north = Coordinates[:north]
+north = Coordinate::NORTH
 ```
 
-All three approaches are equivalent and subject to personal style.
+Treating your enumeration class as a dictionary:
+
+```ruby
+north = Coordinate[:north]
+```
+Note that his method returns `nil` if no enumeration instance is found by the
+specified name.
 
-To retrieve all values of an enumeration, simply invoke `all` method on your
+To retrieve all enumeration instances simply use method `all` on your
 enumeration class:
+
 ```ruby
-coordinates = Coordinates.all
+coordinates = Coordinate.all
 ```
 
-## Development
+### Specifying associated values
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+Each enumeration instance has an implicit name and associated value attributes
+accessible through the `name` and `value` methods. If no associated value is
+specified for an enumeration instance in the definition of the enumeration 
+class, it will be implicitly set to its name:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+north = Coordinate.north
+north.name
+# => :north
+north.value
+# => "north"
+```
+
+You may provide a custom associated value to each enumeration instance following
+its name in the declaration:
+
+```ruby
+class Planet
+  include RubyEnum
+
+  enum :mercury, 1
+  enum :venus, 2
+  enum :earth, 3
+end
+
+mercury = Planet.mercury
+mercury.name
+# => :mercury
+mercury.value
+# => 1
+```
+
+Associated values should be unique in the context of an enumeration class. An 
+error will be thrown in those cases, for example:
+
+```ruby
+class InvalidEnumeration
+  include RubyEnum
+
+  enum :a, 1
+  enum :b, 1
+end
+```
+
+### Finding enumerations by associated value
+
+You can find an enumeration value by its associated value:
+
+```ruby
+mercury = Planet.find_by_value 1
+```
+
+If no enumeration instance is found with the specified associated value this
+method returns `nil`. Using the `find_by_value!` version, an error is raised in
+this case.
+
+### Testing enumeration classes
+
+To test enumeration classes you can use the custom `be_an_enumeration` and
+`define_enumeration_value` matchers.
+
+```ruby
+require 'ruby_enum/rspec'
+
+describe Coordinate do
+
+  it { should be_an_enumeration }
+  it { should define_enumeration_value :north }
+  it { should define_enumeration_value :north, 'north' }
+end
+```
+
+### Adding custom methods
+
+Nothing stops you from adding your own methods to an enumeration.
+
+```ruby
+class Planet
+  include RubyEnum
+
+  enum :mercury, 1
+  enum :venus, 2
+  enum :earth, 3
+
+  def description
+    "#{name.to_s.capitalize} is the #{value.ordinalize} rock from the sun"
+  end
+end
+
+mercury = Planet::EARTH
+mercury.description
+# => "Earth is the 3rd rock from the sun"
+```
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/ruby_enum/fork )
+1. Fork it ( https://github.com/laskaridis/ruby_enum/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/ruby_enum/version.rb

@@ -1,3 +1,3 @@
 module RubyEnum
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/lib/ruby_enum.rb

@@ -3,10 +3,11 @@ require "ruby_enum/version"
 module RubyEnum
 
   def self.included(base)
+    p base
     # enmeration instances are singleton values
     base.private_class_method(:new, :allocate)
-    base.extend(ClassMethods)
-    base.include(InstanceMethods)
+    base.send :extend, ClassMethods
+    base.send :include, InstanceMethods
   end
 
   module InstanceMethods
@@ -28,11 +29,12 @@ module RubyEnum
       end
     end
 
-    # the value associated with the enumeration instance
+    # @return [String] the associated value of the enumeration instance
     def value
       @_value
     end
 
+    # @return [Symbol] the name of the enumeration instance
     def name
       @_name
     end
@@ -60,27 +62,36 @@ module RubyEnum
       self[name] || super
     end
 
-    # defines enumeration values
     def enum(name, value = nil)
+      raise ArgumentError, 'name is required for an enumeration' if name.nil?
+
       normalized_name = _normalize name
       if self[normalized_name]
-        raise ArgumentError, "An enumeration value for #{normalized_name} has " \
+        raise ArgumentError, "an enumeration value for #{normalized_name} has " \
           "already been defined in #{self.name}."
       else
         value = normalized_name.to_s unless value
+        if find_by_value value
+          raise ArgumentError, "duplicate associated value `#{value}` for enumeration" \
+            "with name `#{name}`"
+        end
         _define_instance_accessor_for normalized_name
         _enumeration_values[normalized_name] = new(normalized_name, value)
       end
     end
 
+    # @return the enumeration instance with the specified name or nil if none exists
     def [](name)
       _enumeration_values[_normalize(name)]
     end
 
+    # @return [Array] all enumeration instances defined in this enumeration class
     def all
       _enumeration_values.map { |_, instance| instance }
     end
 
+    # @return the enumeration instance with the specified associated value
+    # @raise [ArgumentError] when no enumeration instance with the associated value is found
     def find_by_value!(value)
       result = find_by_value(value) 
       unless result
@@ -90,6 +101,7 @@ module RubyEnum
       result
     end
 
+    # @return the enumeration instance with the specifed associated value
     def find_by_value(value)
       all.find { |instance| instance.value == value }
     end
@@ -102,10 +114,14 @@ module RubyEnum
 
     def _define_instance_accessor_for(name)
       # check {http://ryanangilly.com/post/234897271/dynamically-adding-class-methods-in-ruby}
+      _metaclass.instance_eval do
+        define_method(name) { return self[name] }
+      end
+    end
+
+    def _metaclass
       class << self
         self
-      end.instance_eval do
-        define_method(name) { return self[name] }
       end
     end
 

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: ruby_enum
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Lefteris Laskaridis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-15 00:00:00.000000000 Z
+date: 2015-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.8'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 3.3.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 3.3.0
 description: Implementation of a simple enumeration type for ruby
@@ -59,7 +59,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- .gitignore
+- .travis.yml
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -71,7 +72,6 @@ files:
 - lib/ruby_enum/rspec.rb
 - lib/ruby_enum/version.rb
 - ruby_enum.gemspec
-- tags
 homepage: https://github.com/laskaridis/ruby_enum
 licenses:
 - MIT
@@ -82,17 +82,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Simple enumeration type for ruby

data/tags

@@ -1,20 +0,0 @@
-!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
-!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
-!_TAG_PROGRAM_AUTHOR	Darren Hiebert	/dhiebert@users.sourceforge.net/
-!_TAG_PROGRAM_NAME	Exuberant Ctags	//
-!_TAG_PROGRAM_URL	http://ctags.sourceforge.net	/official site/
-!_TAG_PROGRAM_VERSION	5.9~svn20110310	//
-ClassMethods	lib/ruby_enum.rb	/^  module ClassMethods$/;"	m	class:RubyEnum
-Coordinates	spec/ruby_enum_spec.rb	/^      class Coordinates$/;"	c
-Member	lib/ruby_enum/member.rb	/^  class Member$/;"	c	class:RubyEnum
-RubyEnum	lib/ruby_enum.rb	/^module RubyEnum$/;"	m
-RubyEnum	lib/ruby_enum/member.rb	/^module RubyEnum$/;"	m
-RubyEnum	lib/ruby_enum/version.rb	/^module RubyEnum$/;"	m
-[]	lib/ruby_enum.rb	/^    def [](member_name)$/;"	f	class:RubyEnum.ClassMethods
-enum	lib/ruby_enum.rb	/^    def enum(name, value = nil)$/;"	f	class:RubyEnum.ClassMethods
-enumeration_members	lib/ruby_enum.rb	/^    def enumeration_members$/;"	f	class:RubyEnum.ClassMethods
-enumeration_value_for	lib/ruby_enum.rb	/^    def enumeration_value_for(member_name)$/;"	f	class:RubyEnum.ClassMethods
-find_enumeration_member_by	lib/ruby_enum.rb	/^    def find_enumeration_member_by(name)$/;"	f	class:RubyEnum.ClassMethods
-included	lib/ruby_enum.rb	/^  def self.included(base)$/;"	F	class:RubyEnum
-initialize	lib/ruby_enum/member.rb	/^    def initialize(name, value = nil)$/;"	f	class:RubyEnum.Member
-method_missing	lib/ruby_enum.rb	/^  def method_missing(name, *args, &blk)$/;"	f	class:RubyEnum