enums 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 65a45b808ac04efdf1cf4b9b299b61882d691605
-  data.tar.gz: fc6259850c15fe3f81ee5d8e2bebf4d40f0a754f
+  metadata.gz: 3fd8c533a33e8a97a70892813fe984a95e9a296f
+  data.tar.gz: f8fc99c3b73a0473b3fe2717d86fd538bf85bdb0
 SHA512:
-  metadata.gz: f4875a80e70ac8099ce8b79b92ec6385edced9606a4e873c2ffd3709dd2d454d6057c4aab302c5fa6f4a78999dd79bf36a0fc910ee216af1bbdaaccdc764f25a
-  data.tar.gz: 38c9a7a44081ecad43ebd9431c3149f48632466499dfea0029532dd036013e8a59add6cd33996cd96cccd61c170e24d3b7ad8803fb41c5c39359d71e20556ba1
+  metadata.gz: 30521b0da15ad85a970ef1fbfae486a4f987501dbd5b729fb370df89e8f0cb179fed63951274374c63322ba93c76ebdd16c6e9a646084f7f2ea960fc81eac30c
+  data.tar.gz: a8d14b650496db549103d58c19d028186a4451887fb46115ac09afcd4177a7f8612cbefdf33ca0c4b804e6c87ff39c1b65a43f88848687d87c8d8fff2ed909ac

data/README.md

@@ -32,8 +32,8 @@ module Color
   BLUE  = 1
   GREEN = 2
 end
-Color::RED   #=> 0
-Color::BLUE  #=> 1
+Color::RED       #=> 0
+Color::BLUE      #=> 1
 Color.constants  #=> [:RED, :BLUE, :GREEN]
 # ...
 ```
@@ -210,14 +210,30 @@ enum :FileAttrib, [:read_only, :hidden, :system, :archive], flags: true
 # -or -
 enum :FileAttrib, :read_only, :hidden, :system, :archive, flags: true
 # -or -
-enum :FileAttrib, { read_only: 1<<0,    # 2^0 = 1  = 0b00000001
-                    hidden:    1<<1,    # 2^1 = 2  = 0b00000010
-                    system:    1<<2,    # 2^2 = 4  = 0b00000100
-                    archive:   1<<5,    # 2^5 = 32 = 0b00100000
+enum :FileAttrib, { read_only: Bit(0),
+                    hidden:    Bit(1),
+                    system:    Bit(2),
+                    archive:   Bit(5),
                   },
                   flags: true
 ```
 
+Aside: What's `Bit()`?
+
+`Bit()` is a bit conversion helper defined as `def Bit(n) 1 << n; end`. Example:
+
+|           | Bit Shift  | Binary        | Decimal     | Hex     |
+|-----------|------------|---------------|-------------|---------|
+| `Bit(0)`  |   `1<<0`   |  `0b00000001` |  `2^0 = 1`  |  `0x01` |
+| `Bit(1)`  |   `1<<1`   |  `0b00000010` |  `2^1 = 2`  |  `0x02` |
+| `Bit(2)`  |   `1<<2`   |  `0b00000100` |  `2^2 = 4`  |  `0x04` |
+| `Bit(3)`  |   `1<<3`   |  `0b00001000` |  `2^3 = 8`  |  `0x08` |
+| `Bit(4)`  |   `1<<4`   |  `0b00010000` |  `2^4 = 16` |  `0x10` |
+| `Bit(5)`  |   `1<<5`   |  `0b00100000` |  `2^5 = 32` |  `0x20` |
+| ...       |
+
+
+
 (Auto-)builds a class and code like:
 
 ``` ruby
@@ -232,11 +248,11 @@ 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 )
+  READ_ONLY = new( :read_only, Bit(0) )
+  HIDDEN    = new( :hidden,    Bit(1) )
+  SYSTEM    = new( :system,    Bit(2) )
+  ARCHIVE   = new( :archive,   Bit(3) )
+  ALL       = new( :all,       Bit(0)|Bit(1)|Bit(2)|Bit(3) )
 
   def self.none()      NONE; end
   def self.read_only() READ_ONLY; end
@@ -245,7 +261,7 @@ class FileAttrib < Flag
   def self.archive()   ARCHIVE; end
   def self.all()       ALL; end
 
-  def self.values()  [1<<0,1<<1,1<<2,1<<3]; end
+  def self.values()  [Bit(0),Bit(1),Bit(2),Bit(3)]; end
   def self.keys()    [:read_only, :hidden, :system, :archive]; end
   def self.members() [READ_ONLY, HIDDEN, SYSTEM, ARCHIVE]; end
 
@@ -258,11 +274,11 @@ class FileAttrib < Flag
   def self.[]( key ) self.key( key ); 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 read_only?()  @value & Bit(0) == Bit(0); end
+  def hidden?()     @value & Bit(1) == Bit(1); end
+  def system?()     @value & Bit(2) == Bit(2); end
+  def archive?()    @value & Bit(3) == Bit(3); end
+  def all?()        @value == Bit(0)|Bit(1)|Bit(2)|Bit(3); end
 
   def member?( other ) @value & other.value == other.value; end
 
@@ -348,9 +364,9 @@ 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
+enum :TextStyle, { bold:      Bit(0),
+                   italic:    Bit(1),
+                   underline: Bit(2)
                  },
                  flags: true
 
@@ -401,6 +417,8 @@ style.is_a? TextStyle     #=> true
 and so on.
 
 
+
+
 ### What about enums for (algebraic) union data types with variants?
 
 Yes, yes, yes. Use the `Union` class or the `data` helper from the safedata library.

data/lib/enums.rb

@@ -10,6 +10,9 @@ require 'enums/version'    # note: let version always go first
 
 ## forward declarations
 module Safe
+
+  ## todo/check/discuss: auto-include SafeHelper - why? why not?
+
   ## note: use ClassMethods pattern for auto-including class methods
   ##   note ClassMethods module is called SafeHelper
   def self.included( klass )
@@ -26,6 +29,11 @@ module Safe
 end # module Safe
 
 
+module Kernel
+  def Bit( n ) 1 << n; end     ## add "global" bit conversion helper
+end
+
+
 
 require 'enums/enum'
 require 'enums/enum_builder'

data/lib/enums/enum.rb

@@ -16,6 +16,28 @@ class Enum
     self
   end
 
+  def self._typecheck_enum!( o )
+    if o.instance_of?( self )
+      o
+    else
+      raise TypeError.new( "[Enum] enum >#{name}< type expected; got >#{o.class.inspect}<" )
+    end
+  end
+  def _typecheck_enum!( o ) self.class._typecheck_enum!( o ); end
+
+
+  def ==( other )
+    if other.is_a?( Integer ) && other == 0   ## note: only allow compare by zero (0) integer - why? why not?
+      @value == 0
+    else
+      @value == _typecheck_enum!( other ).value
+    end
+  end
+  alias_method :eql?, :==
+
+
+
+
 
   def self.keys
     @keys ||= members.map {|member| member.key}.freeze
@@ -29,11 +51,12 @@ class Enum
     @hash_by_key[key]
   end
 
-  def self.[]( key )   ## convenience alias for key
-    self.key( key )
+  class << self
+    alias_method :[], :key    ## convenience alias for key
   end
 
 
+
   def self.values
     @values ||= members.map {|member| member.value}.freeze
     @values
@@ -48,12 +71,13 @@ class Enum
 
 
   def self.zero() members[0]; end
-  def zero?() self == self.class.zero; end
+  def zero?() self == self.class.zero; end  ## note: use compare by identity (object_id) and NOT value e.g. 0
 
 
   def self.size() keys.size; end
-  def self.length() size; end   ## alias (as is the ruby tradition)
-
+  class << self
+    alias_method :length, :size   ## alias (as is the ruby tradition)
+  end
 
   def self.convert( arg )
     ## todo/check: support keys too - why? why not?
@@ -62,5 +86,14 @@ class Enum
     ## note: will ALWAYS look-up by (member) index and NOT by value (integer number value might be different!!)
     members[ arg ]
   end
+
+
+  ## add to_i, to_int - why? why not?
+  def to_i()       @value; end
+  def to_int()     @value; end      ## allows Integer( .. )
+
+  def to_b()       parse_bool(); end
+  def parse_bool() @value != 0; end   ## nonzero == true, zero == false like numbers
+  alias_method :to_bool, :parse_bool
 end  # class Enum
 end  # module Safe

data/lib/enums/flag.rb

@@ -18,7 +18,7 @@ class Flag
   end
 
   def self._typecheck_flag!( o )
-    if self == o.class
+    if o.instance_of?( self )
       o
     else
       raise TypeError.new( "[Flag] flag >#{name}< type expected; got >#{o.class.inspect}<" )
@@ -38,12 +38,10 @@ class Flag
 
 
   def ==( other )
-    if self.class == other.class
-      @value == other.value
-    elsif other.is_a?( Integer )  ## note: also allow compare by "plain" integer
-      @value == other
+    if other.is_a?( Integer ) && other == 0   ## note: only allow compare by zero (0) integer - why? why not?
+      @value == 0
     else
-      false
+      @value == _typecheck_flag!( other ).value
     end
   end
   alias_method :eql?, :==
@@ -103,8 +101,8 @@ class Flag
     @hash_by_key[key]
   end
 
-  def self.[]( key )  ## convenience alias for key
-    self.key( key )
+  class << self
+    alias_method :[], :key  ## convenience alias for key
   end
 
 
@@ -154,8 +152,13 @@ class Flag
 
   ## add size|length too why? why not?
 
+
   ## add to_i, to_int - why? why not?
-  ## def to_i()   @value; end
-  ## def to_int() @value; end
+  def to_i()       @value; end
+  def to_int()     @value; end      ## allows Integer( .. )
+
+  def to_b()       parse_bool(); end
+  def parse_bool() @value != 0; end   ## nonzero == true, zero == false like numbers
+  alias_method :to_bool, :parse_bool
 end  # class Flag
 end # module Safe

data/lib/enums/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enums
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-29 00:00:00.000000000 Z
+date: 2019-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc