banditry 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c854743c128a72638b17245379ce66aeb3266f3e
+  data.tar.gz: 7d2b541357f00ac37354f6e38dd60aa8b9c59526
+SHA512:
+  metadata.gz: 2bdac37736e2c1f3d00f0dc63917676dc93ff4e2cfe5b6986b4df2ab81158506f98ba0d9c906d0fbc891a2c16f37ea2b266cddb879754e1ecb52df1f85d765ed
+  data.tar.gz: 75d713fe996892ff04be45ceb278bba6126e79e30a7d0d9211432b8995a71480b4b4585c96fcc3a7ec63d8b48653750eb814e1b11ae5d3a15811df624d0d8337

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.6
+  - 2.2.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in banditmask.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 John Parker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# [![Gem Version](https://badge.fury.io/rb/banditry.svg)](http://badge.fury.io/rb/banditry) [![Build Status](https://travis-ci.org/jparker/banditry.svg?branch=master)](https://travis-ci.org/jparker/banditry)
+
+# Banditry
+
+Banditry provides a generic wrapper for working with bitmasks.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'banditry'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install banditry
+
+## Usage
+
+### Banditry::BanditMask
+
+Create a class which inherits from Banditry::BanditMask, and declare the
+available bit names and their corresponding values.
+
+```ruby
+class ChmodMask < Banditry::BanditMask
+  bit :read,    0b001
+  bit :write,   0b010
+  bit :execute, 0b100
+end
+
+ChmodMask.bits # => { :read => 1, :write => 2, :execute => 4 }
+```
+
+Instantiate a new mask class:
+
+```ruby
+mask = ChmodMask.new
+# or
+current_bitmask = 0b001 | 0b010
+mask = ChmodMask.new current_bitmask
+```
+
+Enable bits by name.
+
+```ruby
+mask << :read << :execute
+```
+
+Ask whether specific bits are enabled.
+
+```ruby
+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, :execute]
+```
+
+### Banditry
+
+In a class with a bitmask attribute, extend Banditry and call
+Banditry.bandit_mask to add accessor methods for working with the bitmask
+attribute.
+
+```ruby
+class ObjectWithBitmaskAttribute
+  attr_accessor :bitmask
+
+  extend Banditry
+  bandit_mask :bitmask, as: :bits, with: ChmodMask
+end
+
+obj = ObjectWithBitmaskAttribute.new
+obj.bitmask = 0b001
+```
+
+This gives you a reader method which returns the Banditry::BanditMask
+representation of the bitmask attribute.
+
+```ruby
+obj.bits # => #<ChmodMask:0x007f941b9518c8 @bitmask=1>
+```
+
+It also gives you a writer method which lets you modify the bitmask. The
+writer accepts Banditry::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 particular bits are
+set on the bitmask.
+
+```ruby
+obj.bits? :read           # => true
+obj.bits? :write          # => false
+obj.bits? :execute        # => true
+obj.bits? :read, :write   # => false
+obj.bits? :read, :execute # => true
+```
+
+## 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.
+
+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
+
+1. Fork it ( https://github.com/jparker/banditry/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/test_*.rb'
+end
+
+task default: :test

data/banditry.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'banditry/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "banditry"
+  spec.version       = Banditry::VERSION
+  spec.authors       = ["John Parker"]
+  spec.email         = ["jparker@urgetopunt.com"]
+
+  spec.summary       = %q{Generic implementation of a bitmask.}
+  spec.description   = %q{Banditry provides a generic wrapper class to manage a bitmask attribute. Formerly known as "banditmask".}
+  spec.homepage      = "https://github.com/jparker/banditry"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 2.1'
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'minitest', '~> 5.7'
+
+  spec.add_development_dependency 'pry'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "banditry"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start
+
+# require "irb"
+# IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/banditry/bandit_mask.rb

@@ -0,0 +1,161 @@
+module Banditry
+  class BanditMask
+    attr_reader :bitmask
+
+    def initialize(bitmask = nil) # :nodoc:
+      @bitmask = bitmask || 0b0
+    end
+
+    ##
+    # Returns a Hash mapping all defined names to their respective bits.
+    #
+    #   class MyMask < Banditry::BanditMask
+    #     bit :read, 0b01
+    #     bit :write, 0b10
+    #   end
+    #
+    #   MyMask.bits # => { :read => 1, :write => 2 }
+    def self.bits
+      @bits ||= {}
+    end
+
+    ##
+    # Maps +name+ to +value+ in the global list of defined bits.
+    #
+    #   class MyMask < Banditry::BanditMask
+    #     bit :read, 0b001
+    #     bit :write, 0b010
+    #     bit :execute, 0b100
+    #   end
+    def self.bit(name, value)
+      bits.update name => value
+    end
+
+    ##
+    # Returns integer value of current bitmask.
+    def to_i
+      bitmask
+    end
+
+    ##
+    # Returns an array of names of the currently enabled bits.
+    #
+    #   class MyMask < Banditry::BanditMask
+    #     bit :read, 0b01
+    #     bit :write, 0b10
+    #   end
+    #
+    #   mask = MyMask.new 0b01
+    #   mask.bits # => [:read]
+    def bits
+      self.class.bits.select { |bit, _| include? bit }.keys
+    end
+    alias_method :to_a, :bits
+
+    ##
+    # 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 defined with
+    # Banditry::BanditMask.bit.
+    #
+    #   class MyMask < Banditry::BanditMask
+    #     bit :read, 0b01
+    #     bit :write, 0b10
+    #   end
+    #
+    #   mask = MyMask.new       # => #<MyMask:0x007f9ebd44ae40 @bitmask=0>
+    #   mask << :read << :write # => #<MyMask:0x007f9ebd44ae40 @bitmask=3>
+    def <<(bit)
+      @bitmask |= bit_value(bit)
+      self
+    end
+
+    ##
+    # 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 Banditry::BanditMask.bit.
+    #
+    #   class MyMask < Banditry::BanditMask
+    #     bit :read, 0b01
+    #     bit :write, 0b10
+    #   end
+    #
+    #   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 < Banditry::BanditMask
+    #     bit :read, 0b01
+    #     bit :write, 0b10
+    #   end
+    #
+    #   class MyOtherMask < Banditry::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 Banditry::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
+    # Banditry::BanditMask.bit.
+    #
+    #   class MyMask < Banditry::BanditMask
+    #     bit :read, 0b001
+    #     bit :write, 0b010
+    #     bit :execute, 0b100
+    #   end
+    #
+    #   mask = MyMask.new 0b101
+    #
+    #   mask.include? :read           # => true
+    #   mask.include? :write          # => false
+    #   mask.include? :execute        # => true
+    #
+    #   mask.include? :read, :write   # => false
+    #   mask.include? :read, :execute # => true
+    def include?(*bits)
+      raise ArgumentError, 'wrong number of arguments (0 for 1+)' if bits.empty?
+      bits.all? { |bit| bitmask & bit_value(bit) != 0 }
+    end
+
+    private
+
+    ##
+    # Returns the integer value for the bit named +bit+. Raises +ArgumentError+
+    # if +bit+ has not been previously defined with Banditry::BanditMask.bit.
+    def bit_value(bit)
+      self.class.bits.fetch(bit) do
+        raise ArgumentError, "undefined bit: #{bit.inspect}"
+      end
+    end
+  end
+end

data/lib/banditry/version.rb

@@ -0,0 +1,3 @@
+module Banditry
+  VERSION = '0.4.0'
+end

data/lib/banditry.rb

@@ -0,0 +1,94 @@
+require 'banditry/version'
+require 'banditry/bandit_mask'
+
+module Banditry
+  class BanditryError < StandardError
+  end
+
+  class MethodCollisionError < BanditryError
+  end
+
+  ##
+  # Creates wrapper methods for reading, writing, and querying the bitmask
+  # stored in +attribute+ using the class +with+. +with+ defaults to
+  # Banditry::BanditMask, but you can (and probably should) define your own
+  # class inheriting from+Banditry::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 return a Banditry::BanditMask representation of
+  # +attribute+.
+  #
+  # 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 query method that delegates to
+  # Banditry::BanditMask#include? will be added.
+  #
+  #   class FileMask < Banditry::BanditMask
+  #     bit :r, 0b001
+  #     bit :w, 0b010
+  #     bit :x, 0b100
+  #   end
+  #
+  #   class FileObject
+  #     attr_accessor :mode_mask
+  #
+  #     extend Banditry
+  #     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)
+    class_eval do
+      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

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: banditry
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- John Parker
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-07-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.7'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Banditry provides a generic wrapper class to manage a bitmask attribute.
+  Formerly known as "banditmask".
+email:
+- jparker@urgetopunt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- banditry.gemspec
+- bin/console
+- bin/setup
+- lib/banditry.rb
+- lib/banditry/bandit_mask.rb
+- lib/banditry/version.rb
+homepage: https://github.com/jparker/banditry
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Generic implementation of a bitmask.
+test_files: []