cenum 0.1

data/MIT-LICENSE.txt

@@ -0,0 +1,17 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+# C-style enums for ruby
+
+This project is an attempt to provide c-style enums for ruby. It's obviously impossible (and not even desirable) to capture the exact syntax and semantics of c's enums in a ruby implementation, but the major capabilities and usage patterns are supported.
+
+## But ruby has symbols, why do we need enums?
+
+Symbols are great. You should probably keep on using symbols in most of the places that you currently do. There are, however, certain situations that enums are better suited for. For instance:
+
+  * A variable can take on a finite set of known, named, values.
+  > The set of values that a variable can take on define that variable's type. Rather than just scattering symbols throughout your code that modifes the variable, it is frequently helpful to encapsulate the type information in one place. An enum, being a lightweight, in-line class definition, is an ideal place to do this. Examples of this type of situation would be when you need to represent days-of-the-week or drink sizes available
+        DayOfWeek = enum :sun, :mon, :tues, :wed, :thurs, :fri, :sat
+        DrinkSize = enum :small, :medium, :large
+  * A dual name/value representation is needed. This is particularly common when you have a set of possible values with an inherent ordering.
+  > Enums have the property of defining both names and values, so you can sometimes get the best of both worlds by using them.
+        DrinkSize = enum :small, :medium, :large
+        DrinkSize::SMALL < DrinkSize::LARGE  # true
+
+## Basic Usage
+
+    require 'cenum'
+
+    class PetOwner
+
+      Animals = enum :cat, :dog, :bird
+
+      def initialize(animal)
+        @animal = animal || Animals::DOG
+      end
+
+      def pet_says
+        case @animal
+          when Animals::CAT then 'meow'
+          when Animals::DOG then 'woof'
+          when Animals::BIRD then 'tweet'
+        end
+      end
+
+    end
+
+    bird_owner = PetOwner.new(PetOwner::Animals::BIRD)
+
+    bird_owner.pet_says  # 'tweet'
+
+## Features
+
+  * Enums contain a list of their values
+
+        irb> Directions = enum :up, :down, :left, :right
+        irb> Directions.values
+        [:up, :down, :left, :right]
+
+  * Enum values map to integers
+
+        irb> Directions::UP
+        0
+        irb> Directions::DOWN
+        1
+
+  * Enum declaration is type declaration
+
+        irb> Boolean = enum :true, :false
+        irb> yes = Boolean.new(:true)
+        irb> no = Boolean.new(:false)
+        irb> yes == no
+        false
+
+  * Value checks and mutators generated automatically
+
+        irb> Boolean = enum :true, :false
+        irb> yes = Boolean.new(:true)
+        irb> no = Boolean.new(:false)
+        irb> yes.true?
+        true
+        irb> no.true?
+        false
+        irb> maybe = Boolean.new(:true)
+        irb> maybe == yes
+        true
+        irb> maybe.false!
+        irb> maybe == yes
+        false
+        irb> maybe == no
+        true
+
+  * Direct comparison of type instances with value names
+
+        irb> Boolean = enum :true, :false
+        irb> yes = Boolean.new(:true)
+        irb> yes == Boolean::TRUE
+        true
+        irb> yes != Boolean::FALSE
+        true
+
+  * Values can be compared
+
+        irb> up = Directions.new(:up)
+        irb> down = Directions.new(:down)
+        irb> up < down
+        true
+
+  * Values can be compared to their names
+
+        irb> up == :up
+        true
+
+  * Custom value mappings
+
+        irb> Drinks = enum :small, :medium, :large, :infinite => -1
+        irb> Drinks::SMALL
+        0
+        irb> Drinks::MEDIUM
+        1
+        irb> Drinks::INFINITE
+        -1
+
+## Roadmap
+
+  * Improve custom value mappings
+    * Spec
+    * Prevent collisions
+    * Allow non-integer value mappings
+    * Consider using a DSL to improve syntax (gets messy in some cases currently)

data/lib/cenum.rb

@@ -0,0 +1,54 @@
+module Kernel
+
+  class Enum
+
+    def self.constant_name(name)
+      name.to_s.upcase
+    end
+
+    def self.[](name)
+      const_get(constant_name(name))
+    end
+
+    def initialize(name)
+      @value = self.class[name]
+    end
+
+    def <=>(other)
+      case other
+      when Enum
+        @value <=> other.__value__
+      when String, Symbol
+        @value <=> self.class[other]
+      else
+        @value <=> other
+      end
+    end
+    include Comparable
+
+    protected
+
+    def __value__
+      @value
+    end
+
+  end
+
+  def enum(*names)
+    klass = Class.new(Enum)
+    counter = 0
+    names.each do |name|
+      if name.is_a? Hash
+        counter = name.values.first
+        name = name.keys.first
+      end
+      klass.const_set(klass.constant_name(name), counter)
+      klass.send(:define_method, "#{name}?", lambda { @value == klass[name] })
+      klass.send(:define_method, "#{name}!", lambda { @value = klass[name] })
+      counter += 1
+    end
+    (class << klass ; self ; end).send(:define_method, :values){ names }
+    klass
+  end
+
+end

data/lib/version.rb

@@ -0,0 +1,5 @@
+module Kernel
+  class Enum
+    VERSION = "0.1"
+  end
+end

data/spec/cenum_spec.rb

@@ -0,0 +1,71 @@
+require 'spec_helper'
+
+describe 'enum' do
+
+  before :each do
+    @enum = enum :val1, :val2
+  end
+
+  it "is a class" do
+    @enum.should be_a(Class)
+  end
+
+  it "includes its values as constants" do
+    @enum.constants.should include(:VAL1)
+  end
+
+  it "are its values accessible using #values" do
+    @enum.values.should == [:val1, :val2]
+  end
+
+  describe 'value' do
+
+    it "are Fixnum" do
+      @enum::VAL1.should == 0
+      @enum::VAL2.should == 1
+    end
+
+    it "can be instantiated" do
+      val1 = @enum.new(:val1)
+      val1.should be_a(@enum)
+    end
+
+    describe "instantiated" do
+
+      before :each do
+        @val1 = @enum.new(:val1)
+        @val2 = @enum.new(:val2)
+      end
+
+      it "can be compared" do
+        @val1.should == @val1
+        @val1.should_not == @val2
+        @val1.should < @val2
+      end
+
+      it "has value? getter" do
+        @val1.should respond_to(:val1?)
+        @val1.val1?.should be_true
+        @val1.val2?.should be_false
+      end
+
+      it "can change its value" do
+        @val1.should respond_to(:val2!)
+        @val1.val2!
+        @val1.should == @val2
+      end
+
+      it "can be compared to values" do
+        @val1.should == @enum::VAL1
+        @val1.should_not == @enum::VAL2
+      end
+
+      it "can be compared to values name" do
+        @val1.should == :val1
+      end
+
+    end # instantiated
+
+  end # value
+
+end # enum

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require File.join(File.dirname(__FILE__), '../lib', 'cenum')
+
+require 'rspec'
+

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: cenum
+version: !ruby/object:Gem::Version 
+  hash: 9
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Shane Gibbons
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-12 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: 
+email: 
+- shane.r.gibbons@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- MIT-LICENSE.txt
+- lib/version.rb
+- lib/cenum.rb
+- spec/spec_helper.rb
+- spec/cenum_spec.rb
+has_rdoc: true
+homepage: https://github.com/microsage/cenum
+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.5.2
+signing_key: 
+specification_version: 3
+summary: This project is an attempt to provide c-style enums for ruby. It's obviously impossible (and not even desirable) to capture the exact syntax and semantics of c's enums in a ruby implementation, but the major capabilities and usage patterns are supported.
+test_files: 
+- spec/spec_helper.rb
+- spec/cenum_spec.rb