banditmask 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b0ba2ce5f3058aca2b5b0aea9b05215a6b76026f
-  data.tar.gz: 5b41de6797071fc9e82a73da1bd341855a5e5594
+  metadata.gz: 1274b0e400a4133553877fbe39fdf8e7a5a4d66c
+  data.tar.gz: 919cceb675c02361a28b6c8d6e0c252f72a391e2
 SHA512:
-  metadata.gz: 6fbe95e064c17ddf564ef77d757df53c5fab34f648974d412e29e2e8fddf42abc945e17bc74f053419d7d04529b662c173113e35ae64329810c71e4e9c658829
-  data.tar.gz: 60c69509a022d36d2a1d33fa72e94ea41e503ea37b5198a126cf9f2be04ec8ff7dce4addcc33d2d1d2e576ba9672f1ad94cc394724278a0daf3c94725df4b5c4
+  metadata.gz: c1fc4ee2ae4d36e5fa5d5618565c771b239cf80aa51ef5c0ed5da76b8a9342a20fd1683e88fa0e2ef2e2a4f48210b0577cef5f07923224175a6bbdb7fec030a6
+  data.tar.gz: acb861486cb0f63f3a3209ed005e97e9526a8ed9dc4389eed2fa7cae6deb28f36f2455dd0c2e49d8c17c19698d6f57d5b71df7a8c6cab366bc68ac202fde58b2

data/README.md

@@ -1,3 +1,5 @@
+# [![Gem Version](https://badge.fury.io/rb/banditmask.svg)](http://badge.fury.io/rb/banditmask) [![Build Status](https://travis-ci.org/jparker/banditmask.svg?branch=master)](https://travis-ci.org/jparker/banditmask)
+
 # BanditMask
 
 BanditMask provides a generic wrapper for working with bitmasks.
@@ -20,7 +22,7 @@ Or install it yourself as:
 
 ## Usage
 
-Create a class which inherits from BanditMask and declare the available bit
+Create a class which inherits from `BanditMask`, and declare the available bit
 names and their corresponding values.
 
 ```ruby
@@ -33,7 +35,7 @@ end
 ChmodMask.bits # => { :read => 1, :write => 2, :execute => 4 }
 ```
 
-To instantiate a new mask class:
+Instantiate a new mask class:
 
 ```ruby
 mask = ChmodMask.new
@@ -62,11 +64,53 @@ Retrieve a list of all currently enabled bits.
 mask.names # => [:read, :write]
 ```
 
+In an 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
+class ObjectWithBitmaskAttribute
+  attr_accessor :bitmask
+
+  extend BanditMask::Banditry
+  bandit_mask :bitmask, as: :bits, with: ChmodMask
+end
+
+obj = ObjectWithBitmaskAttribute.new
+obj.bitmask = 0b011
+```
+
+This gives you a reader method which delegates to `BanditMask#names`.
+
+```ruby
+obj.bits # => [:read, :write]
+```
+
+It also gives you a writer method which lets you overwrite the bitmask.
+
+```ruby
+obj.bits = [:read, :execute]
+obj.bitmask # => 5
+```
+
+Finally, it gives you a query method for checking whether a particular bit is
+set on the bitmask.
+
+```ruby
+obj.has? :read  # => true
+obj.has? :write # => false
+```
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release` to create a git tag for the version, push git
+commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/banditmask/banditry.rb

@@ -0,0 +1,59 @@
+require 'forwardable'
+
+class BanditMask
+  module Banditry
+    def self.extended(cls) # :nodoc:
+      cls.extend Forwardable
+    end
+
+    ##
+    # 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=+.
+    #
+    # The reader method will call BanditMask#bits to get an array of the
+    # enabled bit names represented by +attribute+.
+    #
+    # The writer method will replace the current bitmask with an Integer
+    # representation of a new BanditMask built up using BanditMask#<<.
+    #
+    # In addition to the accessor methods, a method named +has?+ will be added
+    # which delegates to the BanditMask#include?.
+    #
+    #   class ThingMask < BanditMask
+    #     # ...
+    #     # bit :foo, 0b1
+    #     # ...
+    #   end
+    #
+    #   class Thing
+    #     attr_accessor :bitmask
+    #
+    #     extend BanditMask::Banditry
+    #     bandit_mask :bitmask, as: :bits, with: ThingMask
+    #   end
+    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
+
+        def_delegator wrapper, :include?, :has?
+      end
+    end
+  end
+end

data/lib/banditmask/version.rb

@@ -1,3 +1,3 @@
 class BanditMask
-  VERSION = "0.1.0"
+  VERSION = '0.2.0'
 end

data/lib/banditmask.rb

@@ -1,21 +1,22 @@
-require "banditmask/version"
+require 'banditmask/version'
+require 'banditmask/banditry'
 
 class BanditMask
-  attr_reader :mask
+  attr_reader :bitmask
 
-  def initialize(mask = 0b0) # :nodoc:
-    @mask = mask
+  def initialize(bitmask = 0b0) # :nodoc:
+    @bitmask = bitmask
   end
 
   ##
   # Returns a Hash mapping all defined names to their respective bits.
   #
-  #   class BanditMask
+  #   class MyMask < BanditMask
   #     bit :read, 0b01
   #     bit :write, 0b10
   #   end
   #
-  #   BanditMask.bits # => { :read => 1, :write => 2 }
+  #   MyMask.bits # => { :read => 1, :write => 2 }
   def self.bits
     @bits ||= {}
   end
@@ -23,7 +24,7 @@ class BanditMask
   ##
   # Maps +name+ to +value+ in the global list of defined bits.
   #
-  #   class BanditMask
+  #   class MyMask < BanditMask
   #     bit :read, 0b001
   #     bit :write, 0b010
   #     bit :execute, 0b100
@@ -32,16 +33,10 @@ class BanditMask
     bits.update name => value
   end
 
-  ##
-  # Clears all defined bits.
-  def self.reset_bits!
-    @bits = {}
-  end
-
   ##
   # Returns integer value of current bitmask.
   def to_i
-    mask
+    bitmask
   end
 
   ##
@@ -53,15 +48,15 @@ class BanditMask
   #   end
   #
   #   mask = BanditMask.new 0b01
-  #   mask.names # => [:read]
-  def names
-    self.class.bits.select { |name, _| include? name }.keys
+  #   mask.bits # => [:read]
+  def bits
+    self.class.bits.select { |bit, _| include? bit }.keys
   end
-  alias_method :to_a, :names
+  alias_method :to_a, :bits
 
   ##
-  # Enables the bit named +name+. Returns +self+, so calles to #<< can be
-  # chained (think Array#<<). Raises +ArgumentError+ if +name+ does not
+  # 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.
   #
   #   class BanditMask
@@ -71,14 +66,14 @@ class BanditMask
   #
   #   mask = BanditMask.new
   #   mask << :read << :write
-  def <<(name)
-    @mask |= name_to_bit(name)
+  def <<(bit)
+    @bitmask |= bit_value(bit)
     self
   end
 
   ##
-  # Returns true if +name+ is among the currently enabled bits. Returns false
-  # otherwise. Raises +ArgumentError+ if +name+ does not correspond to a bit
+  # Returns true if +bit+ is among the currently enabled bits. Returns false
+  # otherwise. Raises +ArgumentError+ if +bit+ does not correspond to a bit
   # that was previously declared with BanditMask.bit.
   #
   #   class BanditMask
@@ -89,15 +84,15 @@ class BanditMask
   #   mask = BanditMask.new 0b01
   #   mask.include? :read  # => true
   #   mask.include? :write # => false
-  def include?(name)
-    @mask & name_to_bit(name) != 0
+  def include?(bit)
+    bitmask & bit_value(bit) != 0
   end
 
   private
 
-  def name_to_bit(name)
-    self.class.bits.fetch(name) do
-      raise ArgumentError, "undefined bit: #{name.inspect}"
+  def bit_value(bit)
+    self.class.bits.fetch(bit) do
+      raise ArgumentError, "undefined bit: #{bit.inspect}"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: banditmask
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - John Parker
@@ -69,6 +69,7 @@ files:
 - bin/console
 - bin/setup
 - lib/banditmask.rb
+- lib/banditmask/banditry.rb
 - lib/banditmask/version.rb
 homepage: https://github.com/jparker/banditmask
 licenses: