banditmask 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89f4119902ba1674931d97b169c39ce1037ae2ae
-  data.tar.gz: a5db82f06d10b4bdc8ff6927d9cc872df3f89721
+  metadata.gz: c07c68905cfe2a56b3ba19fa9192604e505fe06e
+  data.tar.gz: 5787ac69e4472405d2e0408203e788128eaabb19
 SHA512:
-  metadata.gz: ec236a1784b37496fde1b63972587ff6bd57249dd7e68b3ae57107b52092274172fc99b188b31e2a0b7b97f04cf4da1f955356c339fb4c47fdb0bb3c0a5a91ce
-  data.tar.gz: 280fb89f74711b141be7a505e4f05756443276322407df26a326681a705116583089af90b4b66aa98349f35238fb9e101b0f775542fd4ece051ceb4d1a1629a2
+  metadata.gz: 5535575ab548f020d6043df8927ba7da1fe90bf094c76894890894f1c9c153dabf6fab2501ed23be227c169a8d53af94c41b579a6631777b0c30611876a51c9e
+  data.tar.gz: b0a80aa7a44e9e02d32465d9bc4c200d697bb5fdefe63239328faad9255e3b387d06fbf5fe44717017ae239be4ec500915b23fc9a70ac3bc3cb8b5eb10e3b3a9

data/README.md

@@ -22,7 +22,9 @@ Or install it yourself as:
 
 ## Usage
 
-Create a class which inherits from `BanditMask`, and declare the available bit
+### BanditMask
+
+Create a class which inherits from BanditMask, and declare the available bit
 names and their corresponding values.
 
 ```ruby
@@ -47,25 +49,29 @@ mask = ChmodMask.new current_bitmask
 Enable bits by name.
 
 ```ruby
-mask << :read << :write
+mask << :read << :execute
 ```
 
 Ask whether specific bits are enabled.
 
 ```ruby
-mask.include? :read    # => true
-mask.include? :write   # => true
-mask.include? :execute # => false
+mask.include? :read           # => true
+mask.include? :write          # => false
+mask.include? :execute        # => true
+mask.include? :read, :write   # => false
+mask.include? :read, :execute # => true
 ```
 
 Retrieve a list of all currently enabled bits.
 
 ```ruby
-mask.bits # => [:read, :write]
+mask.bits # => [:read, :execute]
 ```
 
-In an class with a bitmask attribute, extend `BanditMask::Banditry` and call
-`BanditMask::Banditry.bandit_mask` to add accessor methods for working with the
+### BanditMask::Banditry
+
+In a class with a bitmask attribute, extend BanditMask::Banditry and call
+BanditMask::Banditry.bandit_mask to add accessor methods for working with the
 bitmask attribute.
 
 ```ruby
@@ -77,28 +83,35 @@ class ObjectWithBitmaskAttribute
 end
 
 obj = ObjectWithBitmaskAttribute.new
-obj.bitmask = 0b011
+obj.bitmask = 0b001
 ```
 
-This gives you a reader method which delegates to `BanditMask#bits`.
+This gives you a reader method which returns the BanditMask representation
+of the bitmask attribute.
 
 ```ruby
-obj.bits # => [:read, :write]
+obj.bits # => #<ChmodMask:0x007f941b9518c8 @bitmask=1>
 ```
 
-It also gives you a writer method which lets you overwrite the bitmask.
+It also gives you a writer method which lets you modify the bitmask. The
+writer accepts BanditMask objects or an Array of bits.
 
 ```ruby
+obj.bits |= :write
+obj.bitmask # => 3
 obj.bits = [:read, :execute]
 obj.bitmask # => 5
 ```
 
-Finally, it gives you a query method for checking whether a particular bit is
+Finally, it gives you a query method for checking whether particular bits are
 set on the bitmask.
 
 ```ruby
-obj.has? :read  # => true
-obj.has? :write # => false
+obj.bits? :read           # => true
+obj.bits? :write          # => false
+obj.bits? :execute        # => true
+obj.bits? :read, :write   # => false
+obj.bits? :read, :execute # => true
 ```
 
 ## Development

data/lib/banditmask.rb

@@ -4,8 +4,8 @@ require 'banditmask/banditry'
 class BanditMask
   attr_reader :bitmask
 
-  def initialize(bitmask = 0b0) # :nodoc:
-    @bitmask = bitmask
+  def initialize(bitmask = nil) # :nodoc:
+    @bitmask = bitmask || 0b0
   end
 
   ##
@@ -42,12 +42,12 @@ class BanditMask
   ##
   # Returns an array of names of the currently enabled bits.
   #
-  #   class BanditMask
+  #   class MyMask < BanditMask
   #     bit :read, 0b01
   #     bit :write, 0b10
   #   end
   #
-  #   mask = BanditMask.new 0b01
+  #   mask = MyMask.new 0b01
   #   mask.bits # => [:read]
   def bits
     self.class.bits.select { |bit, _| include? bit }.keys
@@ -57,32 +57,83 @@ class BanditMask
   ##
   # Enables the bit named +bit+. Returns +self+, so calls to #<< can be
   # chained. (Think Array#<<.) Raises +ArgumentError+ if +bit+ does not
-  # correspond to a bit that was previously declared with BanditMask.bit.
+  # correspond to a bit that was previously defined with BanditMask.bit.
   #
-  #   class BanditMask
+  #   class MyMask < BanditMask
   #     bit :read, 0b01
   #     bit :write, 0b10
   #   end
   #
-  #   mask = BanditMask.new
-  #   mask << :read << :write
+  #   mask = MyMask.new       # => #<MyMask:0x007f9ebd44ae40 @bitmask=0>
+  #   mask << :read << :write # => #<MyMask:0x007f9ebd44ae40 @bitmask=3>
   def <<(bit)
     @bitmask |= bit_value(bit)
     self
   end
 
   ##
-  # Returns false if any bit in +bits+ is not enabled. Returns true otherwise.
-  # Raises +ArgumentError+ if +bits+ is empty or if any element in +bits+ does
-  # not correspond to bit that was previously declared with BanditMask.bit.
+  # Returns a new instance with the current bitmask plus +bit+. Raises
+  # +ArgumentError+ if +bit+ does not correspond to a bit that was previously
+  # defined by BanditMask.bit.
+  #
+  #   class MyMask < BanditMask
+  #     bit :read, 0b01
+  #     bit :write, 0b10
+  #   end
   #
-  #   class BanditMask
+  #   mask = MyMask.new 0b01
+  #   mask | :write # => #<MyMask:0x007f9e0bcf5d90 @bitmask=3>
+  def |(bit)
+    self.class.new bitmask | bit_value(bit)
+  end
+
+  ##
+  # Returns +true+ if +other+ is an instance of the same class as +self+ and
+  # they have the same bitmask.
+  #
+  #   class MyMask < BanditMask
+  #     bit :read, 0b01
+  #     bit :write, 0b10
+  #   end
+  #
+  #   class MyOtherMask < BanditMask
+  #     bit :chocolate, 0b01
+  #     bit :vanilla, 0b10
+  #   end
+  #
+  #   a = MyMask.new 0b1
+  #   b = MyMask.new 0b1
+  #   c = MyMask.new 0b0
+  #   d = MyOtherMask.new 0b1
+  #
+  #   a == b # => true
+  #   a == c # => false
+  #   a == d # => false
+  def ==(other)
+    other.class == self.class && other.bitmask == bitmask
+  end
+
+  alias_method :eql?, :==
+
+  ##
+  # Returns an object hash. Two BanditMask objects have identical hashes if
+  # they have identical bitmasks and are instances of the same class.
+  def hash
+    [bitmask, self.class].hash
+  end
+
+  ##
+  # Returns true if every bit in +bits+ is enabled and false otherwise. Raises
+  # +ArgumentError+ if +bits+ is empty or if any element in +bits+ does not
+  # correspond to a bit that was previously defined with BanditMask.bit.
+  #
+  #   class MyMask < BanditMask
   #     bit :read, 0b001
   #     bit :write, 0b010
   #     bit :execute, 0b100
   #   end
   #
-  #   mask = BanditMask.new 0b101
+  #   mask = MyMask.new 0b101
   #
   #   mask.include? :read           # => true
   #   mask.include? :write          # => false
@@ -97,6 +148,9 @@ class BanditMask
 
   private
 
+  ##
+  # Returns the integer value for the bit named +bit+. Raises +ArgumentError+
+  # if +bit+ has not been previously defined with BanditMask.bit.
   def bit_value(bit)
     self.class.bits.fetch(bit) do
       raise ArgumentError, "undefined bit: #{bit.inspect}"

data/lib/banditmask/banditry.rb

@@ -1,54 +1,88 @@
 class BanditMask
+  class MethodCollisionError < StandardError
+  end
+
   module Banditry
     ##
-    # Creates wrapper methods for reading and writing the bitmask stored in
-    # +attribute+ using the class +with+. +with+ defaults to BanditMask, but
-    # you can (and probably) should define your own class descending from
-    # +BanditMask+ to fill this role. The name of the accessor methods will be
-    # derived from +as+, e.g., if +as+ is +:foo+, the reader method will be
-    # +:foo+ and the writer will be +:foo=+.
+    # Creates wrapper methods for reading, writing, and querying the bitmask
+    # stored in +attribute+ using the class +with+. +with+ defaults to
+    # BanditMask, but you can (and probably should) define your own class
+    # inheriting from +BanditMask+ to fill this role. The name of the accessor
+    # methods will be derived from +as+, e.g., if +as+ is +:foo+, the methods
+    # will be named +:foo+, +:foo=+, and +:foo?+.
     #
-    # The reader method will call BanditMask#bits to get an array of the
-    # enabled bit names represented by +attribute+.
+    # The reader method will return a BanditMask representation of +attribute+.
     #
-    # The writer method will replace the current bitmask with an Integer
-    # representation of a new BanditMask built up using BanditMask#<<.
+    # The writer method overwrites the current bitmask if with an Array of
+    # bits, or it updates the current bitmask if sent an individual bit, e.g.,
+    # using +#|+.
     #
-    # In addition to the accessor methods, a method named +has?+ will be added
-    # which delegates to the BanditMask#include?.
+    # In addition to the accessor methods, a query method that delegates to
+    # BanditMask#include? will be added.
     #
-    #   class ThingMask < BanditMask
-    #     # ...
-    #     # bit :foo, 0b1
-    #     # ...
+    #   class FileMask < BanditMask
+    #     bit :r, 0b001
+    #     bit :w, 0b010
+    #     bit :e, 0b100
     #   end
     #
-    #   class Thing
-    #     attr_accessor :bitmask
+    #   class FileObject
+    #     attr_accessor :mode_mask
     #
     #     extend BanditMask::Banditry
-    #     bandit_mask :bitmask, as: :bits, with: ThingMask
+    #     bandit_mask :mode_mask, as: :mode, with: FileMask
     #   end
+    #
+    #   file = FileObject.new
+    #   file.mode_mask       # => nil
+    #   file.mode |= :r
+    #   file.mode_mask       # => 1
+    #   file.mode |= :w
+    #   file.mode_mask       # => 3
+    #   file.mode = [:r, :x]
+    #   file.mode_mask       # => 5
     def bandit_mask(attribute, as:, with: BanditMask)
-      cls = with
-      wrapper = as
-
       class_eval do
-        ##
-        # A reader method which instances a new BanditMask object and calls
-        # BanditMask#bits.
-        define_method wrapper do
-          cls.new(send(attribute)).bits
-        end
-
-        define_method :"#{wrapper}=" do |bits|
-          mask = bits.reduce(cls.new) { |mask, bit| mask << bit }
-          send :"#{attribute}=", Integer(mask)
-        end
-
-        define_method :has? do |*bits|
-          cls.new(send(attribute)).include? *bits
-        end
+        generate_reader attribute, as, with
+        generate_writer attribute, as, with
+        generate_query attribute, as, with
+      end
+    end
+
+    private
+
+    def generate_reader(attr, virt, cls)
+      respond_to? virt and
+        raise MethodCollisionError, "method `#{virt}` already exists"
+
+      define_method virt do
+        instance_variable_get(:"@#{virt}") ||
+          instance_variable_set(:"@#{virt}", cls.new(send(attr)))
+      end
+    end
+
+    def generate_writer(attr, virt, cls)
+      respond_to? :"#{virt}=" and
+        raise MethodCollisionError, "method `#{virt}=` already exists"
+
+      define_method :"#{virt}=" do |bits|
+        mask = case bits
+               when BanditMask
+                 bits
+               else
+                 bits.inject(cls.new) { |bm, bit| bm << bit }
+               end
+        send :"#{attr}=", Integer(mask)
+        instance_variable_set :"@#{virt}", mask
+      end
+    end
+
+    def generate_query(attr, virt, cls)
+      respond_to? :"#{virt}?" and
+        raise MethodCollisionError, "method `#{virt}?` already exists"
+
+      define_method :"#{virt}?" do |*bits|
+        cls.new(send(attr)).include? *bits
       end
     end
   end

data/lib/banditmask/version.rb

@@ -1,3 +1,3 @@
 class BanditMask
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: banditmask
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - John Parker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-07-06 00:00:00.000000000 Z
+date: 2015-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler