nice-enum 0.1.0

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2010, Raphael Robatsch
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * The names of the developers or contributors must not be used to
+      endorse or promote products derived from this software without
+      specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE DEVELOPERS OR CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,196 @@
+= Nice Enumerations for Ruby
+
+Ruby's built-in enumeration support, or the lack thereof, is somewhere in the
+C/C++-Age. An enum in Ruby is usually a class or module with various
+constants set to some values. Attempting to display the enum variables will
+result in their values being displayed, which have no use to the end user of
+the application.
+
+	module Permissions
+		Read = 4
+		Write = 2
+		Execute = 1
+	end
+	
+	permissions = Permissions::Read | Permissions::Write
+	puts permissions
+	# Will output "6" - Altough correct, it won't make any sense for a
+	# computer-illiterate user.
+
+Nice-Enum solves this problem by encapsulating the enum values inside an
+instance of their enclosing class and making the to_s method return the
+name of the constant. The above code translates to
+
+	class Permissions < Flags
+		enum :Read,    4
+		enum :Write,   2
+		enum :Execute, 1
+	end
+	
+	permissions = Permissions::Read | Permissions::Write
+	puts permissions.join(" and ")
+	# Will output "Write and Read".
+
+Nice-Enum contains two classes: Enum and Flags. Instances of Flag will
+automatically figure out it's components when or'd together and provides a
+different to_s method. Otherwise the classes are functionally identical.
+
+Of course, an enum can use anything as it's value type, not only integers.
+The value type must only provide a <=> operator.
+
+= Installation
+
+Using Rubygems:
+
+	gem install nice-enum
+
+Manually:
+
+	git clone git://github.com/raphaelr/nice-enum
+	cd nice-enum
+	rake install
+
+== Usage
+
+	require "nice_enum"
+
+= Features
+
+== From Enums to Fixnums and back
+
+Getting the underlying value from an enum instance is usually not neccessary
+because the Enumeration class will hand method calls automatically down to
+the underlying value:
+
+	puts Permissions::Execute.next  # => 2; Will call 1.next
+
+You can explicitly ask for the underlying value:
+
+	puts Permissions::Execute.value # => 1
+
+The reverse has to be done explicitly, but it's very easy:
+
+	puts Permissions.new(1)         # => Execute
+	puts Permissions.new(3)         # => Execute | Write
+	puts Permissions.new(80)        # => 80
+
+In the last example, the Permission instance is treated as a Permission with
+the name "80" and the value 80.
+
+== Auto-Values
+
+Like in most languages with enum support, you don't have to explicitly provide
+values for enumerations. Nice-Enum will create sequential Fixnums if you don't
+specify them.
+
+	class Suit < Enum
+		enum :Spades    # Will become 0
+		enum :Hearts    # Will become 1
+		enum :Diamonds  # Will become 2
+		enum :Clubs     # Will become 3
+	end
+
+You can also mix explicit and implicit values together:
+
+	class Numbers < Enum
+		enum :Zero
+		enum :One
+		enum :FourtyEight, 48
+		enum :FourtyNine
+	end
+
+Note that eventual gaps aren't filled.
+
+== Iterating over values
+
+	Suit.each { |suit| puts suit }
+	# Outputs: Spades
+	#          Hearts
+	#          Diamonds
+	#          Clubs
+
+The Enum class also includes the Enumerable module so you can do stuff like:
+
+	Suit.map { |suit| suit.name.chop }.each { |suit| puts suit }
+	# Outputs: Spade
+	#          Heart
+	#          Diamond
+	#          Club
+
+== Attributes
+
+If that's not nice enough for you, maybe this is: You can attach any number of
+attributes to enumerations. For example:
+
+	class Number < Enum
+		enum :Zero, 0, :squared => 0
+		enum :One, 1, :note => "Average number of eyes per eyehole", :squared => 1
+		enum :Five, 5, :note => "Number of digits per hand", :squared => 25
+	end
+	
+	Number.each do |enum|
+		puts "#{enum} is squared #{enum.squared} and is special because it is the #{enum.note}."
+	end
+	# Outputs: Zero is squared 0 and is special because it is the nil.
+	#          One is squared 1 and is special because it is the Average number of eyes per eyehole.
+	#          Five is squared 25 and is special because it is the Number of digits per hand.
+
+You can also provide default values for attributes:
+
+	class Number < Enum
+		default :note => "number which is the same if multiplied with one"
+		# ...
+	end
+	# Outputs: Zero is squared 0 and is special because it is the number which is the same if multiplied with one.
+	#          One is squared 1 and is special because it is the Average number of eyes per eyehole.
+	#          Five is squared 25 and is special because it is the Number of digits per hand.
+
+== Instance methods
+
+Since enum values are instances of their enclosing class, you can add methods to them:
+
+	class Number < Enum
+		enum :Zero, 0
+		enum :One, 1
+		enum :Two, 2
+		
+		def square
+			value ** 2
+		end
+	end
+	
+	numbers = Number.to_a
+	numbers << Number.new(3)
+	
+	numbers.each { |number| puts "#{number} squared is #{number.square}." }
+	# Outputs: Zero squared is 0.
+	#          One squared is 1.
+	#          Two squared is 4.
+	#          3 squared is 9.
+
+= License
+
+Copyright (c) 2010, Raphael Robatsch
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+* The names of the developers or contributors must not be used to
+  endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE DEVELOPERS OR CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/nice_enum.rb

@@ -0,0 +1,162 @@
+#--
+# Copyright (c) 2010, Raphael Robatsch
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * The names of the developers or contributors must not be used to
+#       endorse or promote products derived from this software without
+#       specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE DEVELOPERS OR CONTRIBUTORS BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+# Base class for all Enumerations. To create an Enumeration, subclass this
+# class and add enum calls in the class body.
+# There are many samples in README.rdoc and samples/ .
+class Enum
+	include Comparable
+	
+	# Returns the name of the enumeration member. This is the first parameter
+	# passed to +enum+.
+	attr_reader :name
+	
+	# Returns the value of the enumeration member. This is the second parameter
+	# passed to +enum+.
+	attr_reader :value
+	
+	# Compares the value of +self+ with the value of +other+.
+	def <=>(other)
+		other = other.value if other.is_a? self.class
+		return value <=> other
+	end
+	
+	# Returns the name of the enumeration member.
+	def to_s
+		@name
+	end
+	
+	alias old_respond_to? respond_to? # :nodoc:
+	def respond_to?(sym) # :nodoc:
+		old_respond_to?(sym) || @value.respond_to?(sym)
+	end
+	
+	def method_missing(sym, *args, &block) # :nodoc:
+		@value.send(sym, *args, &block)
+	end
+	
+	class << Enum
+		include Enumerable
+		
+		# Returns the +Enum+ instance for the given value. If no enumeration
+		# member has been created for this value, a new instance is created,
+		# setting +name+ to +value.to_s+.
+		def new(value)
+			return @enumvalues[value] if @enumvalues.has_key? value
+			_setup_enumvalue(value, value, allocate)
+		end
+		
+		# Returns the default value for the attribute +attr+. If no default
+		# value has been set, +nil+ is returned.
+		def default_value(attr)
+			@defaults ||= {}
+			@defaults[attr.to_sym]
+		end
+		
+		# Enumerates all known enumeration members.
+		def each
+			@enumvalues ||= {}
+			@enumvalues.each_value { |enumvalue| yield enumvalue }
+		end
+		
+		protected
+		# Adds a new enumeration member to the current enumeration. The
+		# generated member is accessible using the constant +name+. If
+		# +value+ is +nil+, it is set to the highest integer value in
+		# use \+ 1.
+		def enum(name, value = nil, attributes = {})
+			@enumvalues ||= {}
+			value ||= (@enumvalues.values.max || -1) + 1
+			
+			enumvalue = allocate
+			const_set(name, enumvalue)
+			@enumvalues[value] = enumvalue
+			_setup_enumvalue(name, value, enumvalue, attributes)
+		end
+		
+		def _setup_enumvalue(name, value, enumvalue, attributes = {}) # :nodoc:
+			enumvalue.instance_variable_set(:@name, name.to_s)
+			enumvalue.instance_variable_set(:@value, value)
+			attributes.each do |attribute, attr_value|
+				_create_accessor(attribute)
+				enumvalue.instance_variable_set("@#{attribute}", attr_value)
+			end
+			enumvalue
+		end
+		
+		# Sets the default values for the attributes of the enumeration members.
+		# There can be more than one call to +defaults+.
+		def defaults(defs = {})
+			@defaults ||= {}
+			@defaults.merge!(defs)
+		end
+		alias default defaults
+		
+		def _create_accessor(attribute) # :nodoc:
+			define_method(attribute) do
+				instance_variable_get("@#{attribute}") || self.class.default_value(attribute)
+			end
+		end
+	end
+end
+
+# Base class for enumerations in which members can be or'd together to create
+# combinations of them. For example, Unix file permissions can be represented
+# as a flag enumeration with the members <tt>Read = 4</tt>, <tt>Write = 2</tt>
+# and <tt>Execute = 1</tt>. There are many samples in README.rdoc and samples/.
+class Flags < Enum
+	# Returns the individual enumeration members that are contained in +self+.
+	# If the enumeration class contains a member with the value +0+, that
+	# member is only included in the result if there aren't any other members
+	# that are contained in +self+.
+	def flags
+		result = self.class.select { |flag| value & flag != 0 }.sort
+		result = [self.class.new(0)] if result.empty?
+		result
+	end
+	
+	# Joins the result of +flags+ together.
+	def join(seperator = " | ")
+		flags.map { |flag| flag.name }.join(seperator)
+	end
+	alias to_s join
+	
+	# Returns the combination of +self+ and +other+.
+	def |(other)
+		self.class.new(value | other)
+	end
+	
+	# Returns the intersection of +self+ and +other+.
+	def &(other)
+		self.class.new(value & other)
+	end
+	
+	# Bitwise-XORs +self+ with +other+.
+	def ^(other)
+		self.class.new(value ^ other)
+	end
+end

data/samples/deck.rb

@@ -0,0 +1,59 @@
+require "../lib/nice_enum"
+
+module Cards
+	class Suit < Enum
+		enum :Spades
+		enum :Hearts
+		enum :Diamonds
+		enum :Clubs
+	end
+	
+	class Value < Enum
+		enum :Ace,    1,    :score => 11 # For the sake of simplicity
+		enum :Two,    2,    :score => 2
+		enum :Three,  3,    :score => 3
+		enum :Four,   nil,  :score => 4
+		enum :Five,   nil,  :score => 5
+		enum :Six,    nil,  :score => 6
+		enum :Jack,   nil,  :score => 10
+		enum :Queen,  nil,  :score => 10
+		enum :Knight, nil,  :score => 10
+	end
+	
+	class Card
+		attr_accessor :suit
+		attr_accessor :value
+		
+		def initialize(suit, value)
+			@suit = suit
+			@value = value
+		end
+		
+		def to_s
+			"#{value} of #{suit}"
+		end
+	end
+	
+	class Deck
+		def initialize
+			@cards = Suit.map do |suit|
+				Value.map do |value|
+					Card.new(suit, value)
+				end
+			end.flatten.shuffle
+		end
+		
+		def draw(n)
+			@cards.slice!(0, n)
+		end
+	end
+end
+
+deck = Cards::Deck.new
+hand = deck.draw(5)
+
+puts "Your hand:"
+hand.each do |card|
+	puts " - #{card}"
+end
+puts "Blackjack score: #{hand.inject(0) { |score, card| score + card.value.score }}"

data/samples/filemodes.rb

@@ -0,0 +1,20 @@
+require "../lib/nice_enum"
+
+class Permission < Flags
+	enum :None, 0
+	enum :Read, 4
+	enum :Write, 2
+	enum :Execute, 1
+end
+
+file = ARGV[0] || __FILE__
+puts "Permissions on #{file}:"
+
+mode = File.stat(file).mode
+user = Permission.new((mode & 448) >> 6)
+group = Permission.new((mode & 56) >> 3)
+world = Permission.new(mode & 7)
+
+puts "User:  #{user}"
+puts "Group: #{group}"
+puts "World: #{world}"

data/samples/squaring_numbers.rb

@@ -0,0 +1,16 @@
+require "../lib/nice_enum"
+
+class Number < Enum
+	enum :Zero, 0
+	enum :One, 1
+	enum :Two, 2
+	
+	def square
+		value ** 2
+	end
+end
+
+numbers = Number.to_a
+numbers << Number.new(3)
+
+numbers.each { |number| puts "#{number} squared is #{number.square}." }

data/test/attribute_test.rb

@@ -0,0 +1,30 @@
+require "nice_enum"
+require "test/unit"
+
+class AttributeTest < Test::Unit::TestCase
+	class Number < Enum
+		enum :Twenty, 20,
+			:note => "Exact value of e^pi - pi"
+		
+		enum :Ninety, 90,
+			:note => "Square Root of -1"
+		
+		enum :FourtyTwo, 42
+	end
+	
+	def test_respond_to_known_attribute
+		assert Number::Twenty.respond_to?(:note)
+	end
+	
+	def test_get_attribute_from_known_value
+		assert_equal "Exact value of e^pi - pi", Number::Twenty.note
+	end
+	
+	def test_get_attribute_from_unknown_value
+		assert_equal nil, Number.new(8).note
+	end
+	
+	def test_respond_to_unknown_attribute
+		assert !Number::Twenty.respond_to?(:color)
+	end
+end

data/test/const_test.rb

@@ -0,0 +1,47 @@
+require "nice_enum"
+require "test/unit"
+
+class ConstTest < Test::Unit::TestCase
+	class Number < Enum
+		enum :Zero, 0
+		enum :One, 1
+		enum :Two, 2
+	end
+	
+	def test_to_s
+		assert_equal "Zero", Number::Zero.to_s
+	end
+	
+	def test_value_equality
+		assert_equal 2, Number::Two.value
+	end
+	
+	def test_enum_equality
+		assert_equal Number::Zero, Number::Zero
+	end
+	
+	def test_mixed_equality
+		assert_equal Number::Zero, 0
+	end
+	
+	def test_new_stays_same
+		assert_same Number::Zero, Number.new(0)
+	end
+	
+	def test_new_on_undefined_enum_value
+		assert_equal -13, Number.new(-13)
+		assert_equal "-13", Number.new(-13).to_s
+	end
+	
+	def test_respond_to_mirroring
+		assert Number::One.respond_to? :abs
+	end
+	
+	def test_send_mirroring
+		assert_equal -1, -Number::One
+	end
+	
+	def test_enumerable
+		assert_equal [Number::Zero, Number::One, Number::Two], Number.to_a
+	end
+end

data/test/default_attribute_test.rb

@@ -0,0 +1,24 @@
+require "nice_enum"
+require "test/unit"
+
+class DefaultAttributeTest < Test::Unit::TestCase
+	class Number < Enum
+		default :note => "A boring number"
+		
+		enum :Twenty, 20,
+			:note => "Exact value of e^pi - pi"
+		
+		enum :Ninety, 90,
+			:note => "Square Root of -1"
+		
+		enum :FourtyTwo, 42
+	end
+	
+	def test_get_set_attribute
+		assert_equal "Exact value of e^pi - pi", Number::Twenty.note
+	end
+	
+	def test_get_unset_attribute
+		assert_equal "A boring number", Number::FourtyTwo.note
+	end
+end

data/test/default_value_test.rb

@@ -0,0 +1,22 @@
+require "test/unit"
+require "nice_enum"
+
+class DefaultValueTest < Test::Unit::TestCase
+	class Suit < Enum
+		enum :Spades
+		enum :Hearts
+		enum :Green, 48
+		enum :Diamonds
+		enum :Clubs
+	end
+	
+	def test_enum_order
+		assert_equal [Suit::Spades, Suit::Hearts, Suit::Green, Suit::Diamonds, Suit::Clubs], Suit.to_a.sort
+	end
+	
+	def test_values
+		assert_equal 1, Suit::Hearts.value
+		assert_equal 48, Suit::Green.value
+		assert_equal 49, Suit::Diamonds.value
+	end
+end

data/test/flags_test.rb

@@ -0,0 +1,38 @@
+require "test/unit"
+require "nice_enum"
+
+class FlagsTest < Test::Unit::TestCase
+	class Permission < Flags
+		enum :Read, 4
+		enum :Write, 2
+		enum :Execute, 1
+	end
+	
+	def test_binary_operators_return_class
+		assert (Permission::Read | Permission::Write).is_a? Permission
+	end
+	
+	def test_or
+		assert_equal 6, Permission::Read | Permission::Write
+	end
+	
+	def test_and
+		assert_equal Permission::Write, 7 & Permission::Write
+	end
+	
+	def test_xor
+		assert_equal Permission::Read | Permission::Write, 7 ^ Permission::Execute
+	end
+	
+	def test_single_flag
+		assert_equal [Permission::Read], Permission::Read.flags
+	end
+	
+	def test_multi_flags
+		assert_equal [Permission::Write, Permission::Read], Permission.new(6).flags
+	end
+	
+	def test_to_s
+		assert_equal "Execute|Write", Permission.new(3).to_s.gsub(' ', '')
+	end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: nice-enum
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Raphael Robatsch
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-02 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: 
+email: raphaelr@f-m.fm
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/nice_enum.rb
+- samples/deck.rb
+- samples/filemodes.rb
+- samples/squaring_numbers.rb
+- README.rdoc
+- LICENSE
+- test/attribute_test.rb
+- test/const_test.rb
+- test/default_attribute_test.rb
+- test/default_value_test.rb
+- test/flags_test.rb
+has_rdoc: true
+homepage: http://raphaelr.github.com/nice-enum
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Nice Enumerations for Ruby
+test_files: 
+- test/attribute_test.rb
+- test/const_test.rb
+- test/default_attribute_test.rb
+- test/default_value_test.rb
+- test/flags_test.rb