ffi-bit_masks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 297221cec74737fc8f7bb7979a4e0d1bac269816
+  data.tar.gz: ac741bdecf847e163e07e008cce18d795b635787
+SHA512:
+  metadata.gz: 5a8180e2b600f5c91cd9aeacc30f0cc6de01a0f5cf8636dc0f73300a1fec87d434f07c2d2d700440decd80eee997d4f6acbeaa593356a7ec75963a8886d0ca8d
+  data.tar.gz: dde56b83e995fe73ba6d38f1fe85fb40733309c2e5267089792edb18c6e8518faaedd2f69f1ff03a499124c48ce38fb0807d8feb1e216ac893d104298c4d7236

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.md
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,2 @@
+doc/
+pkg/

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "ffi-bit_masks Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,6 @@
+### 0.1.0 / 2013-08-27
+
+* Initial release:
+  * Can map a Hash of flags to their bitmask value.
+  * Can map an Integer bitmask to a Hash of flags.
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2013 Hal Brodigan
+
+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,43 @@
+# ffi-bit_masks
+
+* [Homepage](https://github.com/postmodern/ffi-bit_masks#readme)
+* [Issues](https://github.com/postmodern/ffi-bit_masks/issues)
+* [Documentation](http://rubydoc.info/gems/ffi-bit_masks/frames)
+* [Email](mailto:postmodern.mod3 at gmail.com)
+
+## Description
+
+FFI plugin which adds support for bitmasked types (or flags) to FFI.
+
+## Features
+
+* Can map a Hash of flags to their bitmask value.
+* Can map an Integer bitmask to a Hash of flags.
+
+## Examples
+
+    require 'ffi/bit_masks'
+
+    module MyLibrary
+      extend FFI::Library
+
+      ffi_lib 'foo'
+
+      bit_mask :flags, {foo: 0x1, bar: 0x2, baz: 0x4}
+
+      attach_function :my_func, [:pointer, :size_t, :flags], :int
+    end
+
+## Requirements
+
+* [ffi](https://github.com/ffi/ffi#readme) ~> 1.0
+
+## Install
+
+    $ gem install ffi-bit_masks
+
+## Copyright
+
+Copyright (c) 2012-2013 Hal Brodigan
+
+See {file:LICENSE.txt} for details.

data/Rakefile

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'rake'
+
+begin
+  gem 'rubygems-tasks', '~> 0.2'
+  require 'rubygems/tasks'
+
+  Gem::Tasks.new
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install rubygems-tasks` to install Gem::Tasks."
+end
+
+begin
+  gem 'rspec', '~> 2.4'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new
+rescue LoadError => e
+  task :spec do
+    abort "Please run `gem install rspec` to install RSpec."
+  end
+end
+
+task :test    => :spec
+task :default => :spec
+
+begin
+  gem 'yard', '~> 0.8'
+  require 'yard'
+
+  YARD::Rake::YardocTask.new  
+rescue LoadError => e
+  task :yard do
+    abort "Please run `gem install yard` to install YARD."
+  end
+end
+task :doc => :yard

data/ffi-bit_masks.gemspec

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'ffi/bit_masks/version'
+                  FFI::BitMasks::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/gemspec.yml

@@ -0,0 +1,17 @@
+name: ffi-bit_masks
+summary: Adds support for bit-masked types in FFI.
+description:
+  FFI plugin which adds support for bitmasked types (or flags) to FFI.
+
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/ffi-bit_masks#readme
+
+dependencies:
+  ffi: ~> 1.0
+
+development_dependencies:
+  rspec: ~> 2.4
+  rubygems-tasks: ~> 0.2
+  yard: ~> 0.8

data/lib/ffi/bit_masks.rb

@@ -0,0 +1,31 @@
+require 'ffi/bit_masks/bit_mask'
+require 'ffi/bit_masks/version'
+
+module FFI
+  #
+  # Adds bitmask types to FFI libraries.
+  #
+  module BitMasks
+    #
+    # Defines a new bitmask.
+    #
+    # @param [Symbol] name
+    #   The name of the bitmask.
+    #
+    # @param [Hash{Symbol => Integer}] flags
+    #   The flags and their masks.
+    #
+    # @param [Symbol] type
+    #   The underlying type.
+    #
+    # @return [BitMask]
+    #   The new bitmask.
+    #
+    def bit_mask(name,flags,type=:uint)
+      bit_mask = BitMask.new(flags,type)
+
+      typedef(bit_mask,name)
+      return bit_mask
+    end
+  end
+end

data/lib/ffi/bit_masks/bit_mask.rb

@@ -0,0 +1,187 @@
+require 'ffi'
+
+module FFI
+  module BitMasks
+    #
+    # The bitmask data converter.
+    #
+    class BitMask
+
+      include DataConverter
+
+      #
+      # Flags of the bitmask.
+      #
+      # @return [Hash{Symbol => Integer}]
+      #   The mapping of bit-flags to bitmasks.
+      #
+      attr_reader :flags
+
+      #
+      # The masks of the bitmask.
+      #
+      # @return [Hash{Integer => Symbol}]
+      #   The mapping of bitmasks to bit-flags.
+      #   
+      attr_reader :bitmasks
+
+      #
+      # The underlying native type.
+      #
+      # @return [FFI::Type]
+      #   The FFI primitive.
+      #
+      attr_reader :native_type
+
+      #
+      # Initializes a new bitmask.
+      #
+      # @param [Hash{Symbol => Integer}] flags
+      #   The flags and their masks.
+      #
+      # @param [Symbol] type
+      #   The underlying type.
+      #
+      def initialize(flags,type=:uint)
+        @flags       = flags
+        @bitmasks    = flags.invert
+        @native_type = FFI.find_type(type)
+      end
+
+      #
+      # The Symbols that can be passed to the data converter.
+      #
+      # @return [Array<Symbol>]
+      #   The Array of Symbols.
+      #
+      # @note For compatibility with `FFI::Enum`.
+      #
+      def symbols
+        @flags.keys
+      end
+
+      #
+      # The mapping of acceptable Symbols to their Integer equivalents.
+      #
+      # @return [Hash{Symbol => Integer}]
+      #   The mapping of Symbols.
+      #
+      # @note For compatibility with `FFI::Enum`.
+      #
+      def symbol_map
+        @flags
+      end
+
+      #
+      # @note For compatibility with `FFI::Enum`.
+      #
+      alias to_h    symbol_map
+
+      #
+      # @note For compatibility with `FFI::Enum`.
+      #
+      alias to_hash symbol_map
+
+      #
+      # Maps flags to masks and vice versa.
+      #
+      # @overload [](query)
+      #
+      #   @param [Symbol] query
+      #     The flag name.
+      #
+      #   @return [Integer]
+      #     The mask for the flag.
+      #
+      # @overload [](query)
+      #
+      #   @param [Integer] query
+      #     The mask.
+      #
+      #   @return [Symbol]
+      #     The flag for the mask.
+      #
+      def [](query)
+        case query
+        when Symbol  then @flags[query]
+        when Integer then @bitmasks[query]
+        end
+      end
+
+      #
+      # @note For compatibility with `FFI::Enum`.
+      #
+      alias find []
+
+      #
+      # Converts flags to a bitmask.
+      #
+      # @overload to_native(value)
+      #
+      #   @param [Hash{Symbol => Boolean}] value
+      #     The flags and their values.
+      #
+      #   @return [Integer]
+      #     The bitmask for the given flags.
+      #
+      # @overload to_native(value)
+      #
+      #   @param [#to_int] value
+      #     The raw bitmask.
+      #
+      #   @return [Integer]
+      #     The bitmask.
+      #
+      # @raise [ArgumentError]
+      #
+      def to_native(value,ctx=nil)
+        uint = 0
+
+        case value
+        when Hash
+          uint = 0
+
+          value.each do |flag,value|
+            if (@flags.has_key?(flag) && value)
+              uint |= @flags[flag]
+            end
+          end
+
+          return uint
+        else
+          if value.respond_to?(:to_int)
+            int = value.to_int
+
+            @bitmasks.each_key do |mask|
+              uint |= (int & mask)
+            end
+
+            return uint
+          else
+            raise(ArgumentError,"invalid bitmask value #{value.inspect}")
+          end
+        end
+      end
+
+      #
+      # Converts a bitmask into multiple flags.
+      #
+      # @param [Integer] value
+      #   The raw bitmask.
+      #
+      # @return [Hash{Symbol => Boolean}]
+      #   The flags for the bitmask.
+      #
+      def from_native(value,ctx=nil)
+        flags = {}
+
+        @flags.each do |flag,bitmask|
+          flags[flag] ||= ((value & bitmask) == bitmask)
+        end
+
+        return flags
+      end
+
+    end
+  end
+end

data/lib/ffi/bit_masks/version.rb

@@ -0,0 +1,6 @@
+module FFI
+  module BitMasks
+    # ffi-bit_masks version
+    VERSION = "0.1.0"
+  end
+end

data/spec/bit_mask_spec.rb

@@ -0,0 +1,157 @@
+require 'spec_helper'
+require 'ffi/bit_masks/bit_mask'
+
+describe FFI::BitMasks::BitMask do
+  let(:flags) { {:foo => 0x1, :bar => 0x2, :baz => 0x4} }
+
+  subject { described_class.new(flags) }
+
+  describe "#initialize" do
+    subject { described_class.new(flags) }
+
+    it "should initialize the flags" do
+      subject.flags.should == flags
+    end
+
+    it "should invert the flags into bitmasks" do
+      subject.bitmasks.should == flags.invert
+    end
+
+    it "should default type to uint" do
+      subject.native_type.should == FFI::Type::UINT
+    end
+
+    context "when given a custom type" do
+      subject { described_class.new(flags,:ushort) }
+
+      it "should set native type" do
+        subject.native_type.should == FFI::Type::USHORT
+      end
+    end
+  end
+
+  describe "#symbols" do
+    it "should return the names of the flags" do
+      subject.symbols.should == flags.keys
+    end
+  end
+
+  describe "#symbol_map" do
+    it "should return the flags" do
+      subject.symbol_map.should == flags
+    end
+  end
+
+  describe "#to_h" do
+    it "should return the flags" do
+      subject.to_h.should == flags
+    end
+  end
+
+  describe "#to_hash" do
+    it "should return the flags" do
+      subject.to_hash.should == flags
+    end
+  end
+
+  describe "#[]" do
+    context "when given a Symbol" do
+      it "should lookup the bitmask" do
+        subject[:bar].should == flags[:bar]
+      end
+    end
+
+    context "when given an Integer" do
+      it "should lookup the flag" do
+        subject[flags[:bar]].should == :bar
+      end
+    end
+
+    context "otherwise" do
+      it "should return nil" do
+        subject[Object.new].should be_nil
+      end
+    end
+  end
+
+  describe "#to_native" do
+    context "when given a Hash" do
+      let(:hash) { {:foo => true, :bar => true, :baz => false} }
+
+      it "should bitwise or together the flag masks" do
+        subject.to_native(hash).should == (flags[:foo] | flags[:bar])
+      end
+
+      context "when one of the keys does not correspond to a flag" do
+        let(:hash) { {:foo => true, :bug => true, :baz => true} }
+
+        it "should ignore the key" do
+          subject.to_native(hash).should == (flags[:foo] | flags[:baz])
+        end
+      end
+    end
+
+    context "when an Object that respnds to #to_int" do
+      let(:int) { 0x3 }
+
+      it "should call #to_int" do
+        subject.to_native(int).should == 0x3
+      end
+
+      context "when given a bitmask that contains unknown masks" do
+        let(:int) { flags[:foo] | flags[:bar] | 0x8 | 0x10 }
+
+        it "should filter out the unknown masks" do
+          subject.to_native(int).should == (
+            flags[:foo] | flags[:bar]
+          )
+        end
+      end
+    end
+
+    context "when given an Object that does not respond to #to_int" do
+      it "should raise an ArgumentError" do
+        lambda {
+          subject.to_native(Object.new)
+        }.should raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe "#from_native" do
+    let(:value) { flags[:foo] | flags[:baz] }
+
+    it "should set the flags from the value" do
+      subject.from_native(value).should == {
+        :foo => true,
+        :bar => false,
+        :baz => true
+      }
+    end
+
+    context "when one flag is a combination of other flags" do
+      let(:flags) { {:foo => 0x1, :bar => 0x2, :baz => 0x3} }
+      let(:value) { flags[:foo] | flags[:bar]      }
+
+      it "should set all flags whose bitmasks are present" do
+        subject.from_native(value).should == {
+          :foo => true,
+          :bar => true,
+          :baz => true
+        }
+      end
+    end
+
+    context "when given a value that contains unknown masks" do
+      let(:value) { flags[:foo] | flags[:baz] | 0x8 | 0x10 }
+
+      it "should ignore the unknown flags" do
+        subject.from_native(value).should == {
+          :foo => true,
+          :bar => false,
+          :baz => true
+        }
+      end
+    end
+  end
+end

data/spec/bit_masks_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+require 'ffi/bit_masks'
+
+describe FFI::BitMasks do
+  it "should have a VERSION constant" do
+    subject.const_get('VERSION').should_not be_empty
+  end
+
+  describe "#bit_mask" do
+    subject do
+      mod = Module.new
+      mod.extend FFI::Library
+      mod.extend FFI::BitMasks
+    end
+
+    let(:flags) { {:foo => 0x1, :bar => 0x2, :baz => 0x4} }
+
+    it "should return a BitMask object" do
+      subject.bit_mask(:flags,flags).flags.should == flags
+    end
+
+    it "should define a typedef for the bitmask" do
+      bitmask = subject.bit_mask(:flags,flags)
+
+      subject.find_type(:flags).should be_kind_of(FFI::Type::Mapped)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+gem 'rspec', '~> 2.4'
+require 'rspec'
+require 'ffi/bit_masks/version'
+
+include FFI::BitMasks

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: ffi-bit_masks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Postmodern
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: FFI plugin which adds support for bitmasked types (or flags) to FFI.
+email: postmodern.mod3@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+files:
+- .document
+- .gitignore
+- .rspec
+- .yardopts
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- ffi-bit_masks.gemspec
+- gemspec.yml
+- lib/ffi/bit_masks.rb
+- lib/ffi/bit_masks/bit_mask.rb
+- lib/ffi/bit_masks/version.rb
+- spec/bit_mask_spec.rb
+- spec/bit_masks_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/postmodern/ffi-bit_masks#readme
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.5
+signing_key: 
+specification_version: 4
+summary: Adds support for bit-masked types in FFI.
+test_files: []