enumattr 0.0.3 → 0.0.4

data/Gemfile

@@ -2,7 +2,3 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in enumattr.gemspec
 gemspec
-
-group :development do
-  gem 'rspec'
-end

data/README.ja.md

@@ -0,0 +1,144 @@
+# Enumattr
+
+* 定数値とキーワードをマッピングすることができます
+* クラスはそのマッピングを知っています
+* インスタンスは自身の属性値から、マッピングされたキーワードを知ることができます
+
+## 導入
+
+bundler を利用しているなら、Gemfile に以下の行を加え、
+
+    gem 'enumattr'
+
+以下のコマンドを実行します。
+
+    $ bundle
+
+あるいは自身でインストールすることもできます。
+
+    $ gem install enumattr
+
+## 使い方
+
+### 基本
+
+1. `include Enumattr::Base`
+2. `enumattr :attr_name do ... end` を宣言
+3. `enum :keyword, value` を `do ... end` ブロックのなかで記述
+
+例:
+
+    class User
+      include Enumattr::Base
+
+      attr_accessor :status
+
+      enumattr :status do
+        enum :active,   1
+        enum :inactive, 2
+        enum :deleted,  3
+      end
+
+      def initialize(status)
+        @status = status
+      end
+    end
+
+すると、クラスメソッドとインスタンスメソッドが定義されます。
+
+* クラスメソッド
+  * `User.status_keys` (`{attr_name}_keys`) は、キーワードの集合を返します
+  * `User.status_values` (`{attr_name}_values`) は、値の集合を返します
+  * `User.status_enums` (`{attr_name}_enums`) は Enum オブジェクトの集合を返します
+  * `User.status_enum(:active)` (`{attr_name}_enum(:keyword)`) は、`:keyword` に対応する Enum オブジェクトを返します
+  * `User.status_value(:active)` (`{attr_name}_value(:keyword)`) は、`:keyword` に対応する値を返します
+* インスタンスメソッド
+  * `User#status_key` (`{attr_name}_key`) はマッピングに対応するキーワードを返します
+  * `User#status_enum` (`{attr_name}_enum`) はマッピングに対応する Enum オブジェクトを返します
+  * `User#status_value` (`{attr_name}_value`) は値を返します (`alias status_value status` とほぼ同義です)
+  * `User#status_key = :inactive` (`{attr_name}_key=`) というキーワードによるセッターが定義されます
+  * `User#status_active?` (`{attr_name}_{keyword}?`) という、オブジェクトに尋ねるメソッドが定義されます
+
+_Enum オブジェクト_ (`Enumattr::Enums::Enum`) は、`key` と `value` という属性を持ったオブジェクトです。
+
+例:
+
+    User.status_keys
+    #=> #<Set: {:active, :inactive, :deleted}>
+
+    User.status_values
+    #=> #<Set: {1, 2, 3}>
+
+    User.status_enums
+    #=> #<Set: {#<Enumattr::Enums::Enum:0x007ff58b220618 @container=#<Enumattr::Enums:0x007ff58b2207a8>, #<Enumattr::Enums::Enum:0x007ff58b220488 @container=#<Enumattr::Enums:0x007ff58b2207a8>, @key=:inactive, @value=2, @extras=[]>, #<Enumattr::Enums::Enum:0x007ff58b220488 @container=#<Enumattr::Enums:0x007ff58b2207a8>, @key=:deleted, @value=3, @extras=[]>}>
+
+
+    enum = User.status_enum(:active)
+    #=> #<Enumattr::Enums::Enum:0x007ff58b220618 @container=#<Enumattr::Enums:0x007ff58b2207a8>, @key=:active, @value=1, @extras=[]>
+
+    # Enum オブジェクトは key と value という属性を持っている
+    enum.key
+    #=> :active
+
+    enum.value
+    #=> 1
+
+    User.status_enum(:dummy)
+    #=> nil
+
+    User.status_value(:active)
+    #=> 1
+
+    User.status_value(:dummy)
+    #=> nil
+
+
+    user = User.new(1)
+    #=> #<User:0x007ff58b050dd8 @status=1>
+
+    user.status
+    #=> 1
+
+    user.status_key
+    #=> :active
+
+    user.status_value
+    #=> 1
+
+    user.status_key = :inactive
+    #=> :inactive
+
+    user.status
+    #=> 2
+
+    user.status_active?
+    #=> false
+
+    user.status_inactive?
+    #=> true
+
+### オプション
+
+* `:on`
+  * enumattr に指定している名前と同じメソッドあるいは属性が存在しない場合に、参照すべきメソッドや属性を指定できます
+  * `enumattr :enumattr_name, :on => :existent_attribute do ...`
+* `:enums`
+  * ハッシュで enum オブジェクトのマッピングを定義できます。ブロックによる enum オブジェクトの指定の代替記法です
+  * `enumattr :enumattr_name, :enums => {:keyword1 => value1, :keyword2 => value2}`
+* `:extend`
+  * モジュールを指定して enum オブジェクトを拡張することができます
+  * `enumattr :enumattr_name, :extend => Extension do ...`
+
+## その他の例
+
+_examples/*.rb_ と _spec/enumattr/*.rb_ を参照してください。
+
+## ご意見・ご指導
+
+ご意見やご指導を歓迎しています！
+
+1. Fork して
+2. feature branch を作って (`git checkout -b my-new-feature`)
+3. コミットして (`git commit -am 'Added some feature'`)
+4. branch を push して (`git push origin my-new-feature`)
+5. Pull Request してください

data/README.md

@@ -20,11 +20,11 @@ Or install it yourself as:
 
 ## Usage
 
-### defining
+### Basics
 
 1. `include Enumattr::Base`
-2. declare `enumattr attribute_name do ... end`
-2. `enum :symbol, value` in `do ... end`
+2. declare `enumattr :attr_name do ... end`
+3. `enum :keyword, value` in `do ... end` block
 
 example:
 
@@ -44,112 +44,66 @@ example:
       end
     end
 
-or alternative style
+then defining class methods and instance methods.
 
-1. `include Enumattr::Base`
-2. declare `enumattr attribute_name, :enums => {:symbol => value ...}`
-
-example:
-
-    class User
-      include Enumattr::Base
-
-      attr_accessor :status
-
-      enumattr :status, :enums => {:active => 1, :inactive => 2, :deleted => 3}
-
-      def initialize(status)
-        @status = status
-      end
-    end
-
-### defining options
+* class methods
+  * `User.status_keys` as `{attr_name}_keys` return keyword set
+  * `User.status_values` as `{attr_name}_values` return value set
+  * `User.status_enums` as `{attr_name}_enums` return Enum object set
+  * `User.status_enum(:active)` as `{attr_name}_enum(:keyword)` return an Enum object
+  * `User.status_value(:active)` as `{attr_name}_value(:keyword)` return a value
+* instance methods
+  * `User#status_key` as `{attr_name}_key` return a keyword correspond to mapping
+  * `User#status_enum` as `{attr_name}_enum` return a Enum object correspond to mapping
+  * `User#status_value` as `{attr_name}_value` return a value (`alias status_value status`)
+  * `User#status_key = :inactive` as `{attr_name}_key=` setter by keyword
+  * `User#status_active?` as `{attr_name}_{keyword}?` query method return true or false
 
-    class User
-      include Enumattr::Base
-
-      attr_accessor :status
-
-      # alt enum attribute_name and :on option with real_attribute_name
-      enumattr :use_status, :on => :status do
-        enum :active,   1
-        enum :inactive, 2
-        enum :deleted,  3
-      end
-
-      def initialize(status)
-        @status = status
-      end
-    end
-
-#### class methods
-
-* `#{attribute_name}_enums` return enum set
-* `#{attribute_name}_keys` return  key set
-* `#{attribute_name}_values` return value set
+_Enum object_ (`Enumattr::Enums::Enum`) has `key` and `value` attributes
 
 example:
 
-    User.status_enums
-    #=> #<Set: {#<Enumattr::Enums::Enum:0x8a8d13c @key=:active, @value=1>, #<Enumattr::Enums::Enum:0x8a8d100 @key=:inactive, @value=2>, #<Enumattr::Enums::Enum:0x8a8d0ec @key=:deleted, @value=3>}>
-
     User.status_keys
     #=> #<Set: {:active, :inactive, :deleted}>
 
     User.status_values
     #=> #<Set: {1, 2, 3}>
 
-* `#{attribute_name}_enum(key)` return an enum
-* `#{attribute_name}_value(key)` return a value
+    User.status_enums
+    #=> #<Set: {#<Enumattr::Enums::Enum:0x007ff58b220618 @container=#<Enumattr::Enums:0x007ff58b2207a8>, #<Enumattr::Enums::Enum:0x007ff58b220488 @container=#<Enumattr::Enums:0x007ff58b2207a8>, @key=:inactive, @value=2, @extras=[]>, #<Enumattr::Enums::Enum:0x007ff58b220488 @container=#<Enumattr::Enums:0x007ff58b2207a8>, @key=:deleted, @value=3, @extras=[]>}>
 
-example:
 
-    User.status_enum :active
-    #=> #<Enumattr::Enums::Enum:0x8a8d13c @key=:active, @value=1>
-    
-    User.status_enum :inactive
-    #=> #<Enumattr::Enums::Enum:0x8a8d100 @key=:inactive, @value=2>
-    
-    User.status_enum :dummy
-    #=> nil
-    
-    User.status_value :active
+    enum = User.status_enum(:active)
+    #=> #<Enumattr::Enums::Enum:0x007ff58b220618 @container=#<Enumattr::Enums:0x007ff58b2207a8>, @key=:active, @value=1, @extras=[]>
+
+    # Enum object has key and value attributes
+    enum.key
+    #=> :active
+
+    enum.value
     #=> 1
-    
-    User.status_value :inactive
-    #=> 2
-    
-    User.status_value :dummy
+
+    User.status_enum(:dummy)
     #=> nil
 
-#### instance methods
+    User.status_value(:active)
+    #=> 1
 
-* getters
-  * alias `#{attribute_name}_value` `attribute_name`
-  * `#{attribute_name}_key` return symbol
-  * `#{attribute_name}_enum` return enum
-* setter (if writable)
-  * `#{attribute_name}_key=(key)`
-  
+    User.status_value(:dummy)
+    #=> nil
 
-getters example:
 
     user = User.new(1)
-    #=> #<User:0x8e17dac @status=1>
-    
+    #=> #<User:0x007ff58b050dd8 @status=1>
+
     user.status
     #=> 1
-    
-    user.status_value # alias
-    #=> 1
-    
+
     user.status_key
     #=> :active
-    
-    user.status_enum
-    #=> #<Enumattr::Enums::Enum:0x8de2e68 @key=:active, @value=1>
 
-setter example:
+    user.status_value
+    #=> 1
 
     user.status_key = :inactive
     #=> :inactive
@@ -157,23 +111,27 @@ setter example:
     user.status
     #=> 2
 
-
-* Query Method
-* `#{attribute_name}_#{key}?` return true or false
-
-example:
-
     user.status_active?
     #=> false
-    
+
     user.status_inactive?
     #=> true
-    
-    user.status_deleted?
-    #=> false
-    
-    user.status_dummy?
-    NoMethodError: undefined method `status_dummy?' for #<User:0x8e17dac @status=2>
+
+### Options
+
+* `:on`
+  * specify existent attribute or method if `enumattr_name` attribute or method doesn't exist
+  * `enumattr :enumattr_name, :on => :existent_attribute do ...`
+* `:enums`
+  * altenative enum defining leteral by hash instead of block
+  * `enumattr :enumattr_name, :enums => {:keyword1 => value1, :keyword2 => value2}`
+* `:extend`
+  * enum object extension
+  * `enumattr :enumattr_name, :extend => Extension do ...`
+
+## More examples
+
+see: _examples/*.rb_ and _spec/enumattr/*.rb_
 
 ## Contributing
 

data/enumattr.gemspec

@@ -14,4 +14,6 @@ Gem::Specification.new do |gem|
   gem.name          = "enumattr"
   gem.require_paths = ["lib"]
   gem.version       = Enumattr::VERSION
+
+  gem.add_development_dependency('rspec')
 end

data/lib/enumattr/base.rb

@@ -9,29 +9,18 @@ module Enumattr
     module ClassMethods
       private
       def enumattr(enumattr_name, options = {}, &block)
-        if options[:enums]
-          closure = Proc.new do
-            options[:enums].each{|key, value| enum key, value }
-          end
-        else
-          closure = block
-        end
-
-        context = options.merge(:enumattr => enumattr_name, :base => self)
-
-        enumattrs[enumattr_name] = Enums.new(context, &closure)
-        enumattr_bases[enumattr_name] = options[:on] || enumattr_name
-
-        define_enumattr_class_methods enumattr_name
-        define_enumattr_instance_methods enumattr_name
+        enums = Enums.new(enumattr_name, self, options, &block)
+        enumattrs[enumattr_name] = enums
+        define_enumattr_methods(enumattr_name)
       end
 
       def enumattrs
         @enumattrs ||= {}
       end
 
-      def enumattr_bases
-        @enumattr_bases ||= {}
+      def define_enumattr_methods(enumattr_name)
+        define_enumattr_class_methods(enumattr_name)
+        define_enumattr_instance_methods(enumattr_name)
       end
 
       def define_enumattr_class_methods(enumattr_name)
@@ -66,10 +55,10 @@ module Enumattr
       def define_enumattr_instance_methods(enumattr_name)
         enums = enumattrs[enumattr_name]
         method_prefix = "#{enumattr_name}_"
-        enumattr_base = enumattr_bases[enumattr_name]
+        enumattr_on = enums.opts[:on] || enumattr_name
 
         define_method("#{method_prefix}enum") do
-          value = send enumattr_base
+          value = send enumattr_on
           enums.enum_by_value(value)
         end
 
@@ -79,20 +68,20 @@ module Enumattr
         end
 
         define_method(:"#{method_prefix}value") do
-          send enumattr_base
+          send enumattr_on
         end
 
         # setter by key
         define_method("#{method_prefix}key=") do |new_key|
           new_enum = enums.enum_by_key(new_key)
           new_value = new_enum && new_enum.value
-          send "#{enumattr_base}=", new_value
+          send "#{enumattr_on}=", new_value
         end
 
         # Query methods
         enums.enums.each do |enum|
           define_method("#{method_prefix}#{enum.key}?") do
-            value = send enumattr_base
+            value = send enumattr_on
             value == enum.value
           end
         end

data/lib/enumattr/enums.rb

@@ -3,12 +3,14 @@ require 'set'
 
 module Enumattr
   class Enums
-    attr_reader :context
+    attr_reader :enumattr, :base, :opts
 
-    def initialize(context, &block)
-      @context = context.freeze
-      @set = Set.new
-      instance_eval(&block)
+    def initialize(enumattr, base, opts = {}, &block)
+      @enumattr = enumattr
+      @base     = base
+      @opts     = opts.freeze
+      @set      = enum_set(&block)
+      decorate @set
     end
 
     def enums
@@ -32,21 +34,44 @@ module Enumattr
     end
 
     private
-    def enum(key, value)
-      @set.add Enum.new(key, value, self)
+    def enum_set(&block)
+      if enums_hash = @opts[:enums]
+        closure = proc{ enums_hash.each{|key, value| enum key, value } }
+      else
+        closure = block
+      end
+
+      context = Context.new(self, &closure)
+      context.instance_variable_get(:@set)
     end
 
-    class Enum
-      attr_reader :key, :value
+    def decorate(set)
+      if @opts.has_key?(:extend)
+        set.each{|enum| enum.extend @opts[:extend] }
+      end
+    end
 
-      def initialize(key, value, container)
-        @key = key.to_sym
-        @value = value
+    class Context
+      def initialize(container, &closure)
         @container = container
+        @set = Set.new
+        instance_eval(&closure)
+      end
+
+      private
+      def enum(key, value, *extras)
+        @set.add Enum.new(@container, key, value, *extras)
       end
+    end
 
-      def enums
-        @container.enums
+    class Enum
+      attr_reader :key, :value
+
+      def initialize(container, key, value, *extras)
+        @container = container
+        @key       = key.to_sym
+        @value     = value
+        @extras    = extras
       end
 
       def hash
@@ -57,5 +82,6 @@ module Enumattr
         @key == other.key
       end
     end
+
   end
 end

data/lib/enumattr/version.rb

@@ -1,3 +1,3 @@
 module Enumattr
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/enumattr/enums_spec.rb

@@ -2,119 +2,129 @@
 require 'spec_helper'
 
 describe Enumattr::Enums do
-  let(:enums) do
-    defining_context = {
-      :class     => Object,
-      :enumattr  => :example,
-      :something => :something
-    }
-
-    Enumattr::Enums.new(defining_context) do
-      enum :key1, 1
-      enum :key2, 2
-      enum :key3, 3
+  shared_examples "Enumattr::Enums find methods" do
+    describe "enum_by_key" do
+      context "with :test1" do
+        subject { enums.enum_by_key(:test1) }
+        it { should be_a Enumattr::Enums::Enum }
+        its(:key) { should == :test1 }
+        its(:value) { should == 1 }
+      end
     end
-  end
-
-  describe "#context" do
-    subject { enums.context }
-    it { should be_a Hash }
-    it { should be_frozen }
-  end
 
-  describe "#context contents" do
-    describe ":class" do
-      subject { enums.context[:class] }
-      it { should == Object }
+    describe "enum_by_value" do
+      context "with 1" do
+        subject { enums.enum_by_value(1) }
+        it { should be_a Enumattr::Enums::Enum }
+        its(:key) { should == :test1 }
+        its(:value) { should == 1 }
+      end
     end
 
-    describe ":enumattr" do
-      subject { enums.context[:enumattr] }
-      it { should == :example }
+    describe "enum_by_key :test1" do
+      subject { enums.enum_by_key(:test1) }
+      it { should be_a Enumattr::Enums::Enum }
+      its(:key) { should == :test1 }
+      its(:value) { should == 1 }
     end
 
-    describe ":something" do
-      subject { enums.context[:something] }
-      it { should == :something }
+    describe "enum_by_key :not_registered" do
+      subject { enums.enum_by_key(:not_registered) }
+      it { should be_nil }
     end
   end
 
-  describe "#enums" do
-    subject { enums.enums }
-    it { should be_a Set }
-    it { should have(3).items }
-    it "should have Enumattr::Enums::Enum instances" do
-      should satisfy { |enums|
-        enums.all?{|item| item.is_a? Enumattr::Enums::Enum }
-      }
+  context "with enumattr, base and block" do
+    class EnumsTest1
+      include Enumattr::Base
+
+      attr_accessor :test
+
+      enumattr :test do
+        enum :test1, 1
+        enum :test2, 2
+        enum :test3, 3
+        enum :test4, 4
+        enum :test5, 5
+      end
     end
-  end
 
-  describe "#keys" do
-    subject { enums.keys }
-    it { should be_a Set }
-    it { should have(3).items }
-    it "should have Symbol instances" do
-      should satisfy { |keys|
-        keys.all?{|item| item.is_a? Symbol }
-      }
+    let(:enums) { EnumsTest1.instance_eval("enumattrs[:test]") }
+
+    describe "attributes" do
+      subject { enums }
+      its(:base) { should == EnumsTest1 }
+      its(:enums) { should have(5).enums }
+      its(:opts) { should be_empty }
+      its(:keys) { should == Set.new([:test1, :test2, :test3, :test4, :test5]) }
+      its(:values) { should == Set.new([1, 2, 3, 4, 5]) }
     end
+
+    include_examples "Enumattr::Enums find methods"
+
   end
 
-  describe "#values" do
-    subject { enums.values }
-    it { should be_a Set }
-    it { should have(3).items }
-    it "should have Numeric instances" do
-      should satisfy { |values|
-        values.all?{|item| item.is_a? Numeric }
-      }
+  context "with enumattr, base and :enums option" do
+    class EnumsTest2
+      include Enumattr::Base
+
+      attr_accessor :test
+
+      enumattr :test, :enums => {:test1 => 1, :test2 => 2, :test3 => 3}
     end
-  end
 
-  describe "find methods" do
-    shared_examples "#enum_by_foo(foo) each items" do
-      it { should be_a Enumattr::Enums::Enum }
-      its(:key)   { should == expects[:key] }
-      its(:value) { should == expects[:value] }
+    let(:enums) { EnumsTest2.instance_eval("enumattrs[:test]") }
+
+    describe "attributes" do
+      subject { enums }
+      its(:base) { should == EnumsTest2 }
+      its(:enums) { should have(3).enums }
+      its(:opts) { should_not be_empty }
+      its(:keys) { should == Set.new([:test1, :test2, :test3]) }
+      its(:values) { should == Set.new([1, 2, 3]) }
     end
 
-    samples = [
-      {:key => :key1, :value => 1},
-      {:key => :key2, :value => 2},
-      {:key => :key3, :value => 3},
-    ]
-
-    describe "#enum_by_key(key)" do
-      subject { enums.enum_by_key(key) }
-      samples.each do |sample|
-        context "key: #{sample[:key]}" do
-          let(:key) { sample[:key] }
-          let(:expects) { sample }
-
-          include_examples "#enum_by_foo(foo) each items"
-        end
+    include_examples "Enumattr::Enums find methods"
+  end
+
+  context "with enumattr, base and :extend option" do
+    module NameExteision
+      def name
+        @extras.first
       end
     end
 
-    describe "#enum_by_value(value)" do
-      subject { enums.enum_by_value(value) }
+    class EnumsTest3
+      include Enumattr::Base
 
-      samples.each do |sample|
-        context "value: #{sample[:value]}" do
-          let(:value) { sample[:value] }
-          let(:expects) { sample }
+      attr_accessor :test
 
-          include_examples "#enum_by_foo(foo) each items"
-        end
+      enumattr :test, :extend => NameExteision do
+        enum :test1, 1, "test1 name"
+        enum :test2, 2, "test2 name"
+        enum :test3, 3, "test3 name"
+        enum :test4, 4, "test4 name"
       end
     end
-  end
 
-  describe Enumattr::Enums::Enum do
-    subject { enums.enum_by_key(:key1) }
-    its(:key) { should == :key1 }
-    its(:value) { should == 1 }
-    its(:enums) { should == enums.enums }
+    let(:enums) { EnumsTest3.instance_eval("enumattrs[:test]") }
+
+    describe "attributes" do
+      subject { enums }
+      its(:base) { should == EnumsTest3 }
+      its(:enums) { should have(4).enums }
+      its(:opts) { should_not be_empty }
+      its(:keys) { should == Set.new([:test1, :test2, :test3, :test4]) }
+      its(:values) { should == Set.new([1, 2, 3, 4]) }
+    end
+
+    include_examples "Enumattr::Enums find methods"
+
+    describe "enum_by_key :test1" do
+      describe "extension method" do
+        subject { enums.enum_by_key(:test1) }
+        its(:name) { should == "test1 name" }
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enumattr
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,19 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-30 00:00:00.000000000 Z
-dependencies: []
+date: 2012-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70160534844020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70160534844020
 description: simple enum
 email:
 - aisuiiaisuii@gmail.com
@@ -22,6 +33,7 @@ files:
 - .rspec
 - Gemfile
 - LICENSE
+- README.ja.md
 - README.md
 - Rakefile
 - enumattr.gemspec