enums 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 21d675f9ace380c191b6ee58c484ab192dbdb440
-  data.tar.gz: 42c0d89f1a150c48a432b3c2d1b1fbbe00ac1aa0
+  metadata.gz: 65a45b808ac04efdf1cf4b9b299b61882d691605
+  data.tar.gz: fc6259850c15fe3f81ee5d8e2bebf4d40f0a754f
 SHA512:
-  metadata.gz: f990e4ab5fcc741b1226a3f4eb0d8f9e53f8b2b446d1c8175a4f8bd3464d6fcde42a59cc966735bd2216abc4ec397fd3f043c89254815209c7c61fd0464459ba
-  data.tar.gz: 22ff3b44aea19efd814a45f3ad46184bfaf9df24bbb3e23bb306b91b9f068ff68381de7404293ecb47d5e8b8e6e8d669d92f184d2adcd36ff372740b2c35ce57
+  metadata.gz: f4875a80e70ac8099ce8b79b92ec6385edced9606a4e873c2ffd3709dd2d454d6057c4aab302c5fa6f4a78999dd79bf36a0fc910ee216af1bbdaaccdc764f25a
+  data.tar.gz: 38c9a7a44081ecad43ebd9431c3149f48632466499dfea0029532dd036013e8a59add6cd33996cd96cccd61c170e24d3b7ad8803fb41c5c39359d71e20556ba1

data/README.md

@@ -1,6 +1,6 @@
 # Enums - Safe Enumeration Types
 
-enums library / gem - safe enumeration types - a set of symbolic keys bound to unique integer numbers
+enums library / gem - safe enumeration types - a set of symbolic keys bound to unique integer numbers (incl. bit flags option)
 
 * home  :: [github.com/s6ruby/enums](https://github.com/s6ruby/enums)
 * bugs  :: [github.com/s6ruby/enums/issues](https://github.com/s6ruby/enums/issues)
@@ -50,7 +50,7 @@ enum :Color, :red, :green, :blue
 # or
 enum :Color, [:red, :green, :blue]
 # or
-enum :Color, { red:   0, 
+enum :Color, { red:   0,
                green: 1,
                blue:  2 }
 
@@ -149,8 +149,8 @@ enum :State, :fundraising, :expired_refund, :successful
 # or
 enum :State, [:fundraising, :expired_refund, :successful]
 # or
-enum :State, { fundraising:    0, 
-               expired_refund: 1, 
+enum :State, { fundraising:    0,
+               expired_refund: 1,
                successful:     2 }
 
 
@@ -231,21 +231,25 @@ end
 
 class FileAttrib < Flag
 
+  NONE      = new( :none,      0    )
   READ_ONLY = new( :read_only, 1<<0 )
   HIDDEN    = new( :hidden,    1<<1 )
   SYSTEM    = new( :system,    1<<2 )
   ARCHIVE   = new( :archive,   1<<3 )
+  ALL       = new( :all,       1<<0|1<<1|1<<2|1<<3 )
 
+  def self.none()      NONE; end
   def self.read_only() READ_ONLY; end
   def self.hidden()    HIDDEN; end
   def self.system()    SYSTEM; end
   def self.archive()   ARCHIVE; end
+  def self.all()       ALL; end
 
   def self.values()  [1<<0,1<<1,1<<2,1<<3]; end
   def self.keys()    [:read_only, :hidden, :system, :archive]; end
   def self.members() [READ_ONLY, HIDDEN, SYSTEM, ARCHIVE]; end
 
-  def self.zero() @zero ||= new(0); end
+  def self.zero() NONE; end
 
   def self.key( key )
     @hash_by_key ||= Hash[ keys.zip( members ) ]
@@ -253,10 +257,12 @@ class FileAttrib < Flag
   end
   def self.[]( key ) self.key( key ); end
 
-  def read_only?()  member?( READ_ONLY ); end
-  def hidden?()     member?( HIDDEN ); end
-  def system?()     member?( SYSTEM ); end
-  def archive?()    member?( ARCHIVE ); end
+  def none?         @value == 0; end
+  def read_only?()  @value & 1<<0 == 1<<0; end
+  def hidden?()     @value & 1<<1 == 1<<1; end
+  def system?()     @value & 1<<2 == 1<<2; end
+  def archive?()    @value & 1<<3 == 1<<3; end
+  def all?()        @value == 1<<0|1<<1|1<<2|1<<3; end
 
   def member?( other ) @value & other.value == other.value; end
 
@@ -284,15 +290,11 @@ class FileAttrib < Flag
   alias_method :toggle, :bitwise_xor
 
   # ...
-
-  def initialize( *args )
-    # ...
-  end
 end
 
 
 def FileAttrib( *args )
-  FileAttrib.new( *args )
+  FileAttrib.convert( *args )
 end
 ```
 
@@ -306,20 +308,16 @@ FileAttrib.read_only                      #=> <FileAttrib @key=:read_only, @valu
 FileAttrib::READ_ONLY                     #=> <FileAttrib @key=:read_only, @value=1>
 FileAttribs[:read_only]                    #=> <FileAttrib @key=:read_only, @value=1>
 
-FileAttrib(0)                             #=> <FileAttrib @key=:0000, @value=0>
+FileAttrib(0)                             #=> <FileAttrib @key=:none, @value=0>
 FileAttrib.read_only | FileAttrib.hidden  #=> <FileAttrib @key=:0011, @value=3>
 # -or-
-FileAttrib.new( FileAttrib.read_only | FileAttrib.hidden )
-FileAttrib.new( FileAttrib::READ_ONLY | FileAttrib::HIDDEN )
-FileAttrib.new( :read_only, :hidden )
-# -or-
 FileAttrib( FileAttrib.read_only | FileAttrib.hidden )
 FileAttrib( FileAttrib::READ_ONLY | FileAttrib::HIDDEN )
 FileAttrib( :read_only, :hidden )
 #=> <FileAttrib @key=:0011, @value=3>
 
-attrib  = FileAttrib.new        #=> <FileAttrib @key=:0000, @value=0>
-attrib |= FileAttrib.read_only  #=> <FileAttrib @key=:0001, @value=1>
+attrib  = FileAttrib.none       #=> <FileAttrib @key=:none, @value=0>
+attrib |= FileAttrib.read_only  #=> <FileAttrib @key=:read_only, @value=1>
 attrib.read_only?               #=> true
 # -or-
 attrib.member?( FileAttrib.read_only )                #=> true
@@ -327,12 +325,12 @@ attrib.member?( FileAttrib.READ_ONLY )                #=> true
 attrib.member?( :read_only )                          #=> true
 attrib & FileAttrib.read_only == FileAttrib.read_only #=> true
 
-attrib ^= FileAttrib.read_only  #=> <FileAttrib @key=:0000, @value=0>
+attrib ^= FileAttrib.read_only  #=> <FileAttrib @key=:none, @value=0>
 attrib.read_only?               #=> false
-attrib ^= FileAttrib.read_only  #=> <FileAttrib @key=:0001, @value=1>
+attrib ^= FileAttrib.read_only  #=> <FileAttrib @key=:read_ony, @value=1>
 attrib.read_only?               #=> true
 
-attrib &= ~FileAttrib.read_only #=> <FileAttrib @key=:0000, @value=0>
+attrib &= ~FileAttrib.read_only #=> <FileAttrib @key=:none, @value=0>
 attrib.read_only?               #=> false
 
 attrib.is_a? Flag               #=> true
@@ -340,6 +338,66 @@ attrib.is_a? FileAttrib         #=> true
 # ...
 ```
 
+
+Let's try another example:
+
+``` ruby
+Flag.new( :TextStyle, :bold, :italic, :underline )
+# -or -
+enum :TextStyle, [:bold, :italic, :underline], flags: true
+# -or -
+enum :TextStyle, :bold, :italic, :underline, flags: true
+# -or -
+enum :TextStyle, { bold:      1<<0,
+                   italic:    1<<1,
+                   underline: 1<<2
+                 },
+                 flags: true
+
+
+TextStyle.values  #=> [1, 2, 4]
+TextStyle.keys    #=> [:bold, :italic, :underline]
+
+TextStyle.bold                      #=> <TextStyle @key=:bold, @value=1>
+TextStyle::BOLD                     #=> <TextStyle @key=:bold, @value=1>
+TextStyle[:bold]                    #=> <TextStyle @key=:bold, @value=1>
+
+TextStyle(0)                        #=> <TextStyle @key=:none, @value=0>
+TextStyle.bold | TextStyle.italic   #=> <TextStyle @key=:0011, @value=3>
+# -or-
+TextStyle( TextStyle.bold | TextStyle.italic )
+TextStyle( TextStyle::BOLD | TextStyle::ITALIC )
+TextStyle( :bold, :italic )
+#=> <TextStyle @key=:0011, @value=3>
+
+style  = TextStyle.none   #=> <TextStyle @key=:none, @value=0>
+style |= TextStyle.bold   #=> <TextStyle @key=:bold, @value=1>
+style.bold?               #=> true
+# -or-
+style.member?( TextStyle.bold )             #=> true
+style.member?( TextStyle.BOLD )             #=> true
+style.member?( :bold )                      #=> true
+style & TextStyle.bold == TextStyle.bold    #=> true
+
+style ^= TextStyle.bold   #=> <TextStyle @key=:none, @value=0>
+style.bold?               #=> false
+style ^= TextStyle.bold   #=> <TextStyle @key=:bold, @value=1>
+style.bold?               #=> true
+
+style &= ~TextStyle.bold  #=> <TextStyle @key=:none, @value=0>
+style.bold?               #=> false
+
+style = TextStyle.bold | TextStyle.italic | TextStyle.underline
+#=> <TextStyle @key=:all, @value=7>
+style & TextStyle.all == TextStyle.all  #=> true
+style & TextStyle.all != 0              #=> true
+style.all?                              #=> true
+
+style.is_a? Flag          #=> true
+style.is_a? TextStyle     #=> true
+# ...
+```
+
 and so on.
 
 

data/Rakefile

@@ -5,7 +5,7 @@ Hoe.spec 'enums' do
 
   self.version = Enums::VERSION
 
-  self.summary = "enums - safe enumeration types - a set of symbolic keys bound to unique integer numbers"
+  self.summary = "enums - safe enumeration types - a set of symbolic keys bound to unique integer numbers (incl. bit flags option)"
   self.description = summary
 
   self.urls    = ['https://github.com/s6ruby/enums']

data/lib/enums/flag.rb

@@ -10,47 +10,32 @@ class Flag
   attr_reader :key
   attr_reader :value
 
-  def initialize( *args )
-    fmt = "%08b"
-
-    if args.size == 0
-      @value = 0   ## same as new(0)
-      @key   = :"#{fmt % @value}"   ## use :none for 0 key - why? why not?
-    elsif args.size == 1 && args[0].is_a?(Integer)
-      @value = args[0]
-      @key   = :"#{fmt % @value}"   ## todo: lookup if value is a known flag (with key) - why? why not?
-    elsif args.size == 2 && args[0].is_a?(Symbol) && args[1].is_a?(Integer)
-      @key   = args[0]
-      @value = args[1]
-    else
-      ## assume flag object or symbols
-      @value = 0
-      args.each do |arg|
-        flag = _typecast_flag!( arg )
-        @value |= flag.value
-      end
-      @key = :"#{fmt % @value}"    ## todo: lookup if value is a known flag (with key) - why? why not?
-    end
-    self.freeze  ## make "immutable" - should be a value object like an integer number!!!
-    self # return self for chaining
+  def initialize( key, value )
+    @key   = key
+    @value = value
+    self.freeze
+    self
   end
 
-
-  def _typecheck_flag!( o )
-    if self.class == o.class
+  def self._typecheck_flag!( o )
+    if self == o.class
       o
     else
-      raise TypeError.new( "[Flag] flag >#{self.class.name}< type expected; got >#{o.class.inspect}<" )
+      raise TypeError.new( "[Flag] flag >#{name}< type expected; got >#{o.class.inspect}<" )
     end
   end
 
-  def _typecast_flag!( o )
+  def self._typecast_flag!( o )
     if o.is_a? Symbol   ## auto-convert symbol to flag
-      o = self.class.key( o )  ## lookup symbol in "parent" flags class
+      o = key( o )  ## lookup symbol in "parent" flags class
     end
     _typecheck_flag!( o )
   end
 
+  def _typecheck_flag!( o ) self.class._typecheck_flag!( o ); end
+  def _typecast_flag!( o ) self.class._typecast_flag!( o ); end
+
+
 
   def ==( other )
     if self.class == other.class
@@ -64,56 +49,58 @@ class Flag
   alias_method :eql?, :==
 
 
-  def member?( other ) _member?(_typecast_flag!( other )); end
-  def _member?( other ) @value & other.value == other.value; end
+  def member?( other )
+    other = _typecast_flag!( other )
+    @value & other.value == other.value
+  end
 
 
   def bitwise_or( other )
-    self.class.new( @value | _typecheck_flag!( other ).value )
+    self.class.build( @value | _typecheck_flag!( other ).value )
   end
-  alias_method :|,    :bitwise_or
+  alias_method :|, :bitwise_or
 
   def bitwise_and( other )
-    self.class.new( @value & _typecheck_flag!( other ).value )
+    self.class.build( @value & _typecheck_flag!( other ).value )
   end
   alias_method :&, :bitwise_and
 
   def bitwise_xor( other )
-    self.class.new( @value ^ _typecheck_flag!( other ).value )
+    self.class.build( @value ^ _typecheck_flag!( other ).value )
   end
-  alias_method :^,      :bitwise_xor
+  alias_method :^, :bitwise_xor
 
   def bitwise_inverse
-     self.class.new( ~@value )
+     self.class.build( ~@value )
   end
   alias_method :~, :bitwise_inverse
 
 
   def set( other )  ## note: typecast also allows symbol e.g (:read_only, etc.)
-    self.class.new( @value | _typecast_flag!( other ).value )
+    self.class.build( @value | _typecast_flag!( other ).value )
   end
   alias_method :flag, :set
 
   def unset( other )
-    self.class.new( @value & ~_typecast_flag!( other ).value )
+    self.class.build( @value & ~_typecast_flag!( other ).value )
   end
   alias_method :unflag, :unset
 
   def toggle( other )
-    self.class.new( @value ^ _typecast_flag!( other ).value )
+    self.class.build( @value ^ _typecast_flag!( other ).value )
   end
 
 
 
-
   def self.keys()
-    # note: does NOT include none - why? why not?
+    # note: does NOT include :none (and :all)
     @keys ||= members.map { |member| member.key }.freeze
   end
 
   def self.key( key )
-    @hash ||= Hash[ keys.zip( members ) ].freeze
-    @hash[key]
+    # note: does NOT include :none (and :all)
+    @hash_by_key ||= Hash[ keys.zip( members ) ].freeze
+    @hash_by_key[key]
   end
 
   def self.[]( key )  ## convenience alias for key
@@ -122,23 +109,50 @@ class Flag
 
 
   def self.values()
-    # note: does NOT include none - why? why not?
+    # note: does NOT include :none (and :all)
     @values ||= members.map { |member| member.value }.freeze
   end
 
+  def self.value( value )
+    ## note: adds :none and :all for value lookup
+    @hash_by_value ||= Hash[ values.zip( members ) ].merge( self::NONE.value => self::NONE,
+                                                            self::ALL.value  => self::ALL ).freeze
+    @hash_by_value[value]
+  end
+
+  def self.build( value )
+    o = self.value( value )   # lookup if value is a known flag (with key)
+    o = new( :"#{'%08b' % value}", value )  if o.nil?
+    o
+  end
+
 
-  def self.zero() @zero ||= new(0); end
+  def self.zero() @zero ||= self::NONE; end
   def zero?() @value == 0; end
 
+  def self.none() self::NONE; end
+  def none?() @value == 0; end
+  def self.all() self::ALL; end
+  def all?() @value & self.class::ALL.value == self.class::ALL.value; end
+
 
   def self.convert( *args )
-    new( *args )
+    if args.size == 0
+      self::NONE
+    elsif args.size == 1 && args[0].is_a?(Integer)
+      build( args[0] )
+    else
+      ## assume flag object or symbols
+      value = 0
+      args.each do |arg|
+        flag = _typecast_flag!( arg )
+        value |= flag.value
+      end
+      build( value )
+    end
   end
 
-
   ## add size|length too why? why not?
-  ## add value() lookup?
-  ##   not for now - why? combined values are undefined!! what to return??
 
   ## add to_i, to_int - why? why not?
   ## def to_i()   @value; end

data/lib/enums/flag_builder.rb

@@ -44,12 +44,15 @@ def self.build_class( class_name, *args, **kwargs )
       end
 
       def #{key}?
-        _member?( #{key.upcase} )
+        @value & #{value} == #{value}
       end
 RUBY
   end
 
   klass.class_eval( <<RUBY )
+    NONE = new( :none, 0 )
+    ALL  = new( :all, #{f.values.reduce( 0 ) { |sum, value| sum|value }} )
+
     def self.members
       @members ||= [#{f.keys.map {|key|key.upcase}.join(',')}].freeze
     end

data/lib/enums/version.rb

@@ -6,7 +6,7 @@ module Enums
 
   MAJOR = 1
   MINOR = 3
-  PATCH = 0
+  PATCH = 1
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/test/test_flag.rb

@@ -60,6 +60,19 @@ def test_attrib
   assert_equal :read_only, FileAttrib.read_only.key
   assert_equal 1<<0,       FileAttrib::READ_ONLY.value
   assert_equal :read_only, FileAttrib::READ_ONLY.key
+
+  attrib = FileAttrib.read_only | FileAttrib.hidden
+  assert_equal false, attrib.none?
+  assert_equal false, attrib & FileAttrib.all == FileAttrib.all
+  assert_equal false, attrib.all?
+  assert_equal true,  attrib.read_only?
+  assert_equal true,  attrib.hidden?
+
+  attrib |= FileAttrib.system
+  attrib |= FileAttrib.archive
+  assert_equal true,  attrib & FileAttrib.all == FileAttrib.all
+  assert_equal true,  attrib.all?
+  assert_equal false, attrib.none?
 end
 
 def test_text_style
@@ -70,6 +83,9 @@ def test_text_style
 
    style = TextStyle(0)
    assert_equal true, style == 0
+   assert_equal true, style.zero?
+   assert_equal true, style.none?
+
    style |= TextStyle.bold
    assert_equal true, style.member?( :bold )
    assert_equal true, style.member?( TextStyle.bold )
@@ -83,6 +99,11 @@ def test_text_style
    assert_equal true, style.member?( TextStyle.italic )
    assert_equal true, style & TextStyle.italic == TextStyle.italic
    assert_equal true, style & TextStyle.italic != 0
+
+   style = TextStyle.bold | TextStyle.italic | TextStyle.underline
+   assert_equal true, style & TextStyle.all == TextStyle.all
+   assert_equal true, style & TextStyle.all != 0
+   assert_equal true, style.all?
 end
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enums
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-28 00:00:00.000000000 Z
+date: 2019-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.16'
 description: enums - safe enumeration types - a set of symbolic keys bound to unique
-  integer numbers
+  integer numbers (incl. bit flags option)
 email: wwwmake@googlegroups.com
 executables: []
 extensions: []
@@ -89,5 +89,5 @@ rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: enums - safe enumeration types - a set of symbolic keys bound to unique integer
-  numbers
+  numbers (incl. bit flags option)
 test_files: []