ffi_dry 0.1.3

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Eric Monti
+
+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.rdoc

@@ -0,0 +1,233 @@
+= ffi_dry
+
+Helpers, sugar methods, and new features over Ruby FFI to do some common 
+things and add support for some uncommon ones.
+
+== Requirements
+ 
+* ffi-ffi (>= 0.5.0) - github.com/ffi/ffi
+
+
+== Synopsis
+
+(samples/ in the package for code)
+
+A major feature is a DSL"-like" syntax for declaring structure members
+in FFI::Struct or FFI::ManagedStruct definitions.
+    
+    require 'rubygems'
+    require 'ffi'
+    require 'ffi/dry'
+
+    class SomeStruct < FFI::Struct
+      include FFI::DRY::StructHelper
+
+      # we get a new way of specifying layouts with a 'dsl'-like syntax
+      # The hash containing {:desc => ... } can contain arbitrary keys which 
+      # can be used however we like. dsl_metadata will contain all these
+      # in the class and instance.
+      dsl_layout do
+        field   :field1,  :uint16, :desc => 'this is field 1'
+        field   :field2,  :uint16, :desc => 'this is field 2'
+      end
+    end
+
+    ss0=SomeStruct.new
+
+With the declarations above, we specified :desc hash value in metadata
+Let's check out in our instance.
+
+    pp ss0.dsl_metadata 
+    [{:type=>:uint16, :name=>:field1, :desc=>"this is field 1"},
+     {:type=>:uint16, :name=>:field2, :desc=>"this is field 2"}]
+    # => nil
+
+Or class.
+
+    pp SomeStruct.dsl_metadata
+    #...
+
+We get some additional ways of instantiating and declaring values for free 
+during initialization. (The FFI standard ways still work too)
+
+    raw_data = "\x00\x00\xff\xff"
+
+    ss1=SomeStruct.new :raw => raw_data
+    ss2=SomeStruct.new :raw => raw_data, :field1 => 1, :field2 => 2
+    ss3=SomeStruct.new {|x| x.field1=1 }
+    ss4=SomeStruct.new(:raw => raw_data) {|x| x.field1=1 }
+
+    [ ss0, 
+      ss1, 
+      ss2, 
+      ss3, 
+      ss4 ].each_with_index {|x,i| p ["ss#{i}",[x.field1, x.field2]]}
+
+    # which will produce...
+    # ["ss0", [0, 0]]
+    # ["ss1", [0, 65535]]
+    # ["ss2", [1, 2]]
+    # ["ss3", [1, 0]]
+    # ["ss4", [1, 65535]]
+
+
+Here's a broader example which utilizes that arbitrary ':desc' parameter in a 
+"neighborly" way. This also demonstrates superclasses to add common struct
+features, declaring array fields, as well as nesting other structs.
+
+    require 'rubygems'
+    require 'ffi'
+    require 'ffi/dry'
+
+    class NeighborlyStruct < ::FFI::Struct
+      include ::FFI::DRY::StructHelper
+
+      def self.describe
+        print "Struct: #{self.name}"
+        dsl_metadata().each_with_index do |spec, i|
+          print "  Field #{i}\n"
+          print "    name:  #{spec[:name].inspect}\n"
+          print "    type:  #{spec[:type].inspect}\n"
+          print "    desc:  #{spec[:desc]}\n\n"
+        end
+        print "\n"
+      end
+      def describe;  self.class.describe;  end
+    end
+
+    class TestStruct < NeighborlyStruct
+      dsl_layout do
+        field   :field1,  :uint8,  :desc => "test field 1"
+        field   :field2,  :uint8,  :desc => "test field 2"
+      end
+    end
+
+    class SomeStruct < NeighborlyStruct
+      dsl_layout do
+        field  :kind, :uint8,      :desc => "a type identifier"
+        struct :tst,  TestStruct,  :desc => "a nested TestStruct"
+        field  :len,  :uint8,      :desc => "8-bit size value (>= self.size+2)"
+        array  :str,  [:char,255], 
+            :desc => "a string up to 255 bytes bound by :len"
+      end
+
+      # override kind getter method with our own
+      # resolves kind to some kind of type array for example...
+      def kind
+        [:default, :bar, :baz][ self[:kind] ]
+      end
+    end
+
+    s1=TestStruct.new
+    s2=SomeStruct.new
+
+    # check out that 'kind' override:
+    s2.kind
+    # => :default
+
+    # oh and the regular FFI way is always intact
+    s2[:kind]
+    # => 0
+
+    s2[:kind]=1
+    s2.kind
+    # => :bar
+
+    s2.kind=3
+    s2.kind
+    # => :baz
+
+    puts "*"*70
+    s1.describe
+    ## we get a dump of metadata
+    # **********************************************************************
+    # Struct: TestStruct  
+    # Field 0
+    #   name:  :field1
+    #   type:  :uint8
+    #   desc:  test field 1
+    #
+    # Field 1
+    #   name:  :field2
+    #   type:  :uint8
+    #   desc:  test field 2
+
+    puts "*"*70
+    s2.describe
+    ## we get a dump of metadata
+    # Struct: SomeStruct  Field 0
+    #     name:  :kind
+    #     type:  :uint8
+    #     desc:  a type identifier
+    #
+    #   Field 1
+    #     name:  :tst
+    #     type:  TestStruct
+    #     desc:  a nested TestStruct
+    #
+    #   Field 2
+    #     name:  :len
+    #     type:  :uint8
+    #     desc:  8-bit size value (>= self.size+2)
+    #
+    #   Field 3
+    #     name:  :str
+    #     type:  [:char, 255]
+    #     desc:  a string up to 255 bytes bound by :len
+
+    puts "*"*70
+    s2.tst.describe
+    ## same as s1.describe
+    # **********************************************************************
+    # Struct: TestStruct  
+    # Field 0
+    #   name:  :field1
+    #   type:  :uint8
+    #   desc:  test field 1
+    #
+    # Field 1
+    #   name:  :field2
+    #   type:  :uint8
+    #   desc:  test field 2
+
+There's also some helpers for collecting lookup maps for constants, a common
+and handy thing when porting various libraries. We use Socket here just for
+example purposes, you can 'slurp' constants form any namespace this way.
+
+    require 'ffi/dry'
+    require 'socket'
+
+    module AddressFamily
+      include FFI::DRY::ConstMap
+      slurp_constants ::Socket, "AF_"
+      def list ; @@list ||= super() ; end  # only generate the hash once
+    end
+
+AddressFamily now has all the constants it found for Socket::AF_* minus the
+prefix.
+
+   AddressFamily::INET
+   AddressFamily::LINK
+   AddressFamily::INET6
+
+etc...
+
+We can do type or value lookups using []
+
+    AddressFamily[2]      # => "INET"
+    AddressFamily["INET"] # => 2
+    
+We can get a hash of all constant->value pairs with .list
+
+    AddressFamily.list
+    # => {"NATM"=>31, "DLI"=>13, "UNIX"=>1, "NETBIOS"=>33,  ...}
+
+... and invert for a reverse mapping
+
+    AddressFamily.list.invert
+    # => {16=>"APPLETALK", 5=>"CHAOS", 27=>"NDRV", 0=>"UNSPEC", ...}
+
+
+== License
+
+Copyright (c) 2009 Eric Monti. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,60 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ffi_dry"
+    gem.summary = %Q{Syntactic sugar and helper utilities for FFI}
+    gem.description = %Q{Provides a some useful modules, classes, and methods as well as a DSL-like syntax for FFI::Struct layouts}
+    gem.email = "emonti@matasano.com"
+    gem.homepage = "http://github.com/emonti/ffi_dry"
+    gem.authors = ["Eric Monti"]
+#    gem.add_dependency "ffi", ">= 0.5.0"
+    gem.add_development_dependency "rspec"
+    gem.add_development_dependency "yard"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end
+
+require 'rake/rdoctask' 
+Rake::RDocTask.new do |rdoc| 
+  if File.exist?('VERSION') 
+    version = File.read('VERSION') 
+  else 
+    version = "" 
+  end 
+ 
+  rdoc.rdoc_dir = 'rdoc' 
+  rdoc.title = "ffi_dry #{version}" 
+  rdoc.rdoc_files.include('README*') 
+  rdoc.rdoc_files.include('lib/**/*.rb') 
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.3

data/ffi_dry.gemspec

@@ -0,0 +1,60 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ffi_dry}
+  s.version = "0.1.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Eric Monti"]
+  s.date = %q{2009-09-16}
+  s.description = %q{Provides a some useful modules, classes, and methods as well as a DSL-like syntax for FFI::Struct layouts}
+  s.email = %q{emonti@matasano.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "ffi_dry.gemspec",
+     "lib/ffi/dry.rb",
+     "lib/ffi_dry.rb",
+     "samples/afmap.rb",
+     "samples/basic.rb",
+     "samples/describer.rb",
+     "spec/ffi_dry_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/emonti/ffi_dry}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Syntactic sugar and helper utilities for FFI}
+  s.test_files = [
+    "spec/ffi_dry_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+  end
+end

data/lib/ffi/dry.rb

@@ -0,0 +1,366 @@
+begin; require 'rubygems'; rescue LoadError; end
+
+require 'ffi'
+
+module FFI::DRY
+  
+  # A module to add syntactic sugar and some nice automatic getter/setter
+  # logic to FFI::Struct, FFI::ManagedStruct, etc.
+  #
+  # For example:
+  #    require 'rubygems'
+  #    require 'ffi'
+  #    require 'ffi/dry'
+  #    require 'pp'
+  #
+  #    class SomeStruct < FFI::Struct
+  #      include FFI::DRY::StructHelper
+  #
+  #      # we get a new way of specifying layouts with a 'dsl'-like syntax
+  #      dsl_layout do
+  #        field   :field1,  :uint16, :desc => 'this is field 1'
+  #        field   :field2,  :uint16, :desc => 'this is field 2'
+  #      end
+  #    end
+  #
+  #    ss0=SomeStruct.new
+  #
+  #    pp ss0.dsl_metadata   # we can look at definition metadata
+  #
+  #    # produces...
+  #    #  [{:type=>:uint16, :name=>:field1, :desc=>"this is field 1"},
+  #    #   {:type=>:uint16, :name=>:field2, :desc=>"this is field 2"}]
+  #
+  #    # And we have additional ways of instantiating and declaring values
+  #    # during initialization. (The FFI standard ways still work too)
+  #
+  #    raw_data = "\x00\x00\xff\xff"
+  #
+  #    ss1=SomeStruct.new :raw => raw_data
+  #    ss2=SomeStruct.new :raw => raw_data, :field1 => 1, :field2 => 2
+  #    ss3=SomeStruct.new {|x| x.field1=1 }
+  #    ss4=SomeStruct.new(:raw => raw_data) {|x| x.field1=1 }
+  #
+  #    [ ss0, 
+  #      ss1, 
+  #      ss2, 
+  #      ss3, 
+  #      ss4].each_with_index {|x,i| pp ["ss#{i}",[x.field1, x.field2]]}
+  #
+  #     # produces...
+  #     # ["ss0", [0, 0]]
+  #     # ["ss1", [0, 65535]]
+  #     # ["ss2", [1, 2]]
+  #     # ["ss3", [1, 0]]
+  #     # ["ss4", [1, 65535]]
+  #
+  module StructHelper #< ::FFI::Struct
+
+    attr_reader :dsl_metadata
+
+    # Adds field setting on initialization to ::FFI::Struct.new as well as
+    # a "yield(self) if block_given?" at the end.
+    #
+    # The field initialization kicks in if there is only one argument, and it 
+    # is a Hash. 
+    #
+    # Note: 
+    # The :raw parameter is a special tag in the hash. The value is taken as a 
+    # string and initialized into a new FFI::MemoryPointer which this Struct 
+    # then overlays.
+    #
+    # If your struct layout has a field named :raw field, it won't be 
+    # assignable through the hash argument.
+    #
+    # See also: set_fields() which is called automatically on the hash, minus
+    # the :raw tag.
+    #
+    def initialize(*args)
+      @dsl_metadata = self.class.dsl_metadata
+      params=nil
+
+      if args.size == 1 and (oparams=args[0]).is_a? Hash
+        params = oparams.dup
+        if raw=params.delete(:raw)
+          super( ::FFI::MemoryPointer.from_string(raw) )
+        else
+          super()
+        end
+      else
+        super(*args)
+      end
+
+      set_fields(params)
+      yield self if block_given?
+    end
+
+    # Sets field values in the struct specified by their symbolic name from a 
+    # hash of ':field => value' pairs. Uses accessor field wrapper methods 
+    # instead of a direct reference to the field (as in "obj.field1 = x", 
+    # not "obj[:field] = x"). The difference is subtle, but this allows you
+    # to take advantage of any wrapper methods you override when initializing
+    # a new object. The only caveat is that the wrapper method must be named
+    # the same as the field, and the field must be included in members() from
+    # the layout.
+    #
+    # This method is called automatically if you are using the initialize() 
+    # method provided in the DryStruct class and passing it a Hash as its only
+    # argument.
+    def set_fields(params=nil)
+      (params || {}).keys.each do |p|
+        if members().include?(p)
+          self.__send__(:"#{p}=", params[p])
+        else
+          raise(::ArgumentError, "#{self.class} does not have a '#{p}' field")
+        end
+      end
+    end
+
+    # Returns a new instance of self.class containing a seperately allocated 
+    # copy of all our data. This abstract method should usually be called 
+    # with super() from overridden 'copy' implementations for structures
+    # containing pointers to other memory or variable length data at the end. 
+    #
+    # Note also that, by default, this implementation determine's size 
+    # automatically based on the structure size. This is comparable to 
+    # sizeof(some_struct) in C. However, you can supply a 'grown' parameter 
+    # which can be used to add to the size of the copied instance as it is 
+    # allocated and copied.
+    def copy(grown=0)
+      self.class.new( :raw => self.to_ptr.read_string(self.size+grown) )
+    end
+
+    # Returns a pointer to the specified field, which is the name assigned
+    # to a member in the layout.
+    def ptr_to(field)
+      x = self[field] # this is actually a test, to raise if missing
+      return (self.to_ptr + self.offset_of(field))
+    end
+
+    # Contains dsl_layout and some support methods that an 'includee' of
+    # DryStructHelper will have available as class methods.
+    module ClassMethods
+      # returns the structure metadata for this class based on 
+      # the dsl_layout definitions
+      def dsl_metadata
+        @dsl_metadata
+      end
+
+      private
+
+      # This passes a block to an instance of DSL_StructLayoutBuilder, allowing
+      # for a more declarative syntax.
+      #
+      # It is a replacement to layout() and stores the dsl_metadata gathered
+      # about structure members locally.
+      #
+      #   
+      def dsl_layout &block
+        builder = DSL_StructLayoutBuilder.new(self)
+        builder.instance_eval(&block)
+        @layout = builder.build
+        @size = @layout.size
+        _class_meths_from_dsl_metadata( builder.metadata )
+        return @layout
+      end
+
+      def _class_meths_from_dsl_metadata(meta)
+        (@dsl_metadata = meta).each do |spec|
+          name = spec[:name]
+          type = spec[:type]
+          define_method(:"#{name}") do 
+            self[name]
+          end unless instance_methods.include?(:"#{name}")
+          define_method(:"#{name}=") do |val|
+            self[name]=val
+          end unless instance_methods.include?(:"#{name}=")
+        end
+      end
+    end
+    
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end # class StructHelper
+
+  # This is a wrapper around the FFI::StructLayoutBuilder. Its goal is to 
+  # provides a more declarative syntax for defining structures and include
+  # the ability to attach arbitrary dsl_metadata information to structure 
+  # fields during definition.
+  #
+  # The "DSL" (and that's really very in-quotes) supplies 3 ways to
+  # define a field (for now):
+  #
+  #   field()
+  #   array()
+  #   struct()
+  #
+  # See the individual method descriptions for more info.
+  #
+  class DSL_StructLayoutBuilder
+    attr_reader :builder, :metadata
+
+    # Initializes the builder with a reference to the structure using it
+    # Instead of duplicating Struct features, we just call back to them.
+    def initialize(pbind)
+      @pbind = pbind
+      @builder = ::FFI::StructLayoutBuilder.new
+      @metadata = []
+      super()
+    end
+
+    # calls StructLayoutBuider.build() on the bulder and returns its
+    # result.
+    def build
+      @builder.build
+    end
+
+    # Calls StructLayoutBuilder.add_struct() on the builder and stores
+    # a metadata hash entry (the opts hash with name and type overridden)
+    #
+    #   struct field_name,  RubyClass, { ... metadata ... }
+    #
+    # :offset is a special key in metadata, specifies the offset of the field.
+    def struct(name, klass, o={})
+      unless klass.kind_of?(Class) and klass < ::FFI::Struct
+        raise(::ArgumentError, "klass must be a struct")
+      end
+
+      opts = o.merge(:name => name, :type => klass)
+      offset = opts[:offset]
+      ret=@builder.add_struct(name, klass, offset)
+      @metadata << opts
+      return ret
+    end
+
+    # Calls StructLayoutBuider.add_array() on the builder and stores 
+    # a metadata hash entry (the opts hash with name and type overridden)
+    #
+    # Syntax:
+    #
+    #   array field_name, [ctype, N], { ... metadata ... }
+    #
+    # :offset is a special key in metadata, specifies the offset of the field.
+    def array(name, type, o={})
+      unless type.kind_of?(::Array)
+        raise(::ArgumentError, "type must be an array") 
+      end
+
+      opts = o.merge(:name => name, :type => type)
+      offset = opts[:offset]
+      mod = enclosing_module
+      ret= 
+        if @builder.respond_to?(:add_array)
+          @builder.add_array(name, find_type(type[0], mod), type[1], offset)
+        else
+          @builder.add_field(name, type, offset)
+        end
+
+      @metadata << opts
+      return ret
+    end
+
+    # Calls StructLayoutBuider.add_field() on the builder and stores 
+    # a metadata hash entry (the opts hash with name and type overridden)
+    #
+    # Syntax:
+    #
+    #   field field_name, ctype, { ... metadata ... }
+    #
+    # :offset is a special key in metadata, specifies the offset of the field.
+    def field(name, type, o={})
+      opts = o.merge(:name => name, :type => type)
+      offset = opts[:offset]
+      mod = enclosing_module
+      ret= @builder.add_field(name, find_type(type, mod), offset)
+      @metadata << opts
+      return ret
+    end
+
+    def find_type(*args)
+      @pbind.find_type(*args)
+    end
+
+    def enclosing_module(*args)
+      @pbind.enclosing_module(*args)
+    end
+
+  end
+
+  # Used for creating various value <=> constant mapping namespace modules.
+  module ConstMap
+
+    def self.included(klass)
+      klass.extend(ConstMap)
+    end
+
+    # A flexible lookup. Takes 'arg' as a Symbol or String as a name to lookup 
+    # a value, or an Integer to lookup a corresponding name.
+    def [](arg)
+      if arg.is_a? Integer
+        list.invert[arg]
+      elsif arg.is_a? String or arg.is_a? Symbol
+        list[arg.to_s.upcase]
+      end
+    end
+
+    # Generates a hash of all the constant names mapped to value. Usually,
+    # it's a good idea to override this like so in derived modules:
+    #
+    #   def list; @@list = super() ; end
+    #
+    def list
+      constants.inject({}){|h,c| h.merge! c => const_get(c) }
+    end
+
+    private
+      # When called from a module definition or class method, this method 
+      # imports all the constants from # namespace 'nspace' that start with 
+      # into the local namespace as constants named with whatever follows the 
+      # prefix. Only constant names that match [A-Z][A-Z0-9_]+ are imported, 
+      # the rest are ignored.
+      #
+      # This method also yields the (short) constant name and value to a block
+      # if one is provided. The block works like [...].select {|c,v| ... } in
+      # that the value is not mapped if the block returns nil or false.
+      def slurp_constants(nspace, prefix)
+        nspace.constants.grep(/^(#{prefix}([A-Z][A-Z0-9_]+))$/) do
+          c = $2
+          v = nspace.const_get($1)
+          next if block_given? and not yield(c,v)
+          const_set c, v
+        end
+      end
+  end
+
+  # Behaves just like ConstFlags, except that the [nnn] returns a list
+  # of names for the flags set on nnn. Name string lookups work same way as 
+  # ConstFlags.
+  module ConstFlagsMap
+    include ConstMap
+
+    def self.included(klass)
+      klass.extend(ConstFlagsMap)
+    end
+
+    # A flexible lookup. Takes 'arg' as a Symbol or String as a name to lookup 
+    # a bit-flag value, or an Integer to lookup a corresponding names for the 
+    # flags present in it.
+    def [](arg)
+      if arg.is_a? Integer
+        ret = []
+        if arg == 0
+          n = list.invert[0]
+          ret << n if n
+        else
+          list.invert.sort.each {|v,n| ret << n if v !=0 and (v & arg) == v }
+        end
+        return ret
+      elsif arg.is_a? String or arg.is_a? Symbol
+        list[arg.to_s.upcase]
+      end
+    end
+  end
+end
+
+

data/lib/ffi_dry.rb

@@ -0,0 +1 @@
+require 'ffi/dry'

data/samples/afmap.rb

@@ -0,0 +1,28 @@
+require 'ffi/dry'
+require 'socket'
+
+module AddressFamily
+  include FFI::DRY::ConstMap
+  slurp_constants ::Socket, "AF_"
+  def list ; @@list ||= super() ; end
+end
+
+# AddressFamily now has all the constants it found for Socket::AF_*
+#
+# i.e. AddressFamily::INET
+#      AddressFamily::LINK
+#      AddressFamily::INET6
+#      etc...
+#
+# We can do quick lookups
+#     AddressFamily[2]      # => "INET"
+#     AddressFamily["INET"] # => 2
+#
+# We can get a hash of all key-value pairs with .list
+#     AddressFamily.list
+#     # => {"NATM"=>31, "DLI"=>13, "UNIX"=>1, "NETBIOS"=>33,  ...}
+#
+# ... which can be inverted for a reverse mapping
+#     AddressFamily.list.invert
+#     # => {16=>"APPLETALK", 5=>"CHAOS", 27=>"NDRV", 0=>"UNSPEC", ...}
+#

data/samples/basic.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# One major feature is a dsl"-like" syntax for declaring structure members
+# in FFI::Struct or FFI::ManagedStruct definitions.
+    
+    require 'rubygems'
+    require 'ffi'
+    require 'ffi/dry'
+
+    class SomeStruct < FFI::Struct
+      include FFI::DRY::StructHelper
+
+      # we get a new way of specifying layouts with a 'dsl'-like syntax
+      # The hash containing {:desc => ... } can contain arbitrary keys which 
+      # can be used however we like. dsl_metadata will contain all these
+      # in the class and instance.
+      dsl_layout do
+        field   :field1,  :uint16, :desc => 'this is field 1'
+        field   :field2,  :uint16, :desc => 'this is field 2'
+      end
+    end
+
+    ss0=SomeStruct.new
+
+# With the declaration above, we specified :desc hash value, which was stored
+# in metadata along with the field name and type.
+
+    pp ss0.dsl_metadata 
+    [{:type=>:uint16, :name=>:field1, :desc=>"this is field 1"},
+     {:type=>:uint16, :name=>:field2, :desc=>"this is field 2"}]
+    # => nil
+
+
+# We get some free additional ways of instantiating and declaring values during 
+# initialization. (The FFI standard ways still work too)
+
+    raw_data = "\x00\x00\xff\xff"
+
+    ss1=SomeStruct.new :raw => raw_data
+    ss2=SomeStruct.new :raw => raw_data, :field1 => 1, :field2 => 2
+    ss3=SomeStruct.new {|x| x.field1=1 }
+    ss4=SomeStruct.new(:raw => raw_data) {|x| x.field1=1 }
+
+    [ ss0, 
+      ss1, 
+      ss2, 
+      ss3, 
+      ss4 ].each_with_index {|x,i| p ["ss#{i}",[x.field1, x.field2]]}
+
+# which should produce...
+# ["ss0", [0, 0]]
+# ["ss1", [0, 65535]]
+# ["ss2", [1, 2]]
+# ["ss3", [1, 0]]
+# ["ss4", [1, 65535]]
+

data/samples/describer.rb

@@ -0,0 +1,119 @@
+# Here's a broader example which utilizes that arbitrary ':desc' parameter in a 
+# "neighborly" way. This also demonstrates superclasses to add common struct
+# features, declaring array fields, as well as nesting other structs.
+
+    require 'rubygems'
+    require 'ffi'
+    require 'ffi/dry'
+
+    class NeighborlyStruct < ::FFI::Struct
+      include ::FFI::DRY::StructHelper
+
+      def self.describe
+        print "Struct: #{self.name}"
+        dsl_metadata().each_with_index do |spec, i|
+          print "  Field #{i}\n"
+          print "    name:  #{spec[:name].inspect}\n"
+          print "    type:  #{spec[:type].inspect}\n"
+          print "    desc:  #{spec[:desc]}\n\n"
+        end
+        print "\n"
+      end
+      def describe;  self.class.describe;  end
+    end
+
+    class TestStruct < NeighborlyStruct
+      dsl_layout do
+        field   :field1,  :uint8,  :desc => "test field 1"
+        field   :field2,  :uint8,  :desc => "test field 2"
+      end
+    end
+
+    class SomeStruct < NeighborlyStruct
+      dsl_layout do
+        field  :kind, :uint8,      :desc => "a type identifier"
+        struct :tst,  TestStruct,  :desc => "a nested TestStruct"
+        field  :len,  :uint8,      :desc => "8-bit size value (>= self.size+2)"
+        array  :str,  [:char,255], 
+            :desc => "a string up to 255 bytes bound by :len"
+      end
+
+      # override kind getter method with our own
+      # resolves kind to some kind of type array for example...
+      def kind
+        [:default, :bar, :baz][ self[:kind] ]
+      end
+    end
+
+    s1=TestStruct.new
+    s2=SomeStruct.new
+
+    # check out that 'kind' override:
+    s2.kind
+    # => :default
+
+    # oh and the regular FFI way is always intact
+    s2[:kind]
+    # => 0
+
+    s2[:kind]=1
+    s2.kind
+    # => :bar
+
+    s2.kind=3
+    s2.kind
+    # => :baz
+
+    puts "*"*70
+    s1.describe
+    ## we get a dump of metadata
+    # **********************************************************************
+    # Struct: TestStruct  
+    # Field 0
+    #   name:  :field1
+    #   type:  :uint8
+    #   desc:  test field 1
+    #
+    # Field 1
+    #   name:  :field2
+    #   type:  :uint8
+    #   desc:  test field 2
+
+    puts "*"*70
+    s2.describe
+    ## we get a dump of metadata
+    # Struct: SomeStruct  Field 0
+    #     name:  :kind
+    #     type:  :uint8
+    #     desc:  a type identifier
+    #
+    #   Field 1
+    #     name:  :tst
+    #     type:  TestStruct
+    #     desc:  a nested TestStruct
+    #
+    #   Field 2
+    #     name:  :len
+    #     type:  :uint8
+    #     desc:  8-bit size value (>= self.size+2)
+    #
+    #   Field 3
+    #     name:  :str
+    #     type:  [:char, 255]
+    #     desc:  a string up to 255 bytes bound by :len
+
+    puts "*"*70
+    s2.tst.describe
+    ## same as s1.describe
+    # **********************************************************************
+    # Struct: TestStruct  
+    # Field 0
+    #   name:  :field1
+    #   type:  :uint8
+    #   desc:  test field 1
+    #
+    # Field 1
+    #   name:  :field2
+    #   type:  :uint8
+    #   desc:  test field 2
+

data/spec/ffi_dry_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "FfiDry" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'ffi_dry'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: ffi_dry
+version: !ruby/object:Gem::Version 
+  version: 0.1.3
+platform: ruby
+authors: 
+- Eric Monti
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-16 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Provides a some useful modules, classes, and methods as well as a DSL-like syntax for FFI::Struct layouts
+email: emonti@matasano.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- ffi_dry.gemspec
+- lib/ffi/dry.rb
+- lib/ffi_dry.rb
+- samples/afmap.rb
+- samples/basic.rb
+- samples/describer.rb
+- spec/ffi_dry_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/emonti/ffi_dry
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: Syntactic sugar and helper utilities for FFI
+test_files: 
+- spec/ffi_dry_spec.rb
+- spec/spec_helper.rb