ffi_dry 0.1.5 → 0.1.7

data/History.txt

@@ -1,3 +1,24 @@
+=== 0.1.7 / 2010-2-05
+  * Fixed bugs with FFI::Unions
+  * Revamped the dsl_layout builder so that it just wraps layout() instead of
+    attempting to duplicate its functionlity. This will hopefully stop causing
+    compatibility issues with FFI as it changes its internals and new versions 
+    are released.
+  * :p_struct is an attribute that can be used on any field with a type of 
+    :pointer.
+  * Added new experimental feature for the DSL where new fields can be defined
+    by their name as a method name in dsl_layout {} instead of having to 
+    prefix field/array/struct for each.
+  * A warning is now issued when a struct field name cannot be mapped to an
+    accessor method because it would cause a conflict. These used to just be
+    silently skipped. Now the warning is issued if warnings are enabled.
+
+=== 0.1.6 / 2010-1-18
+  * support win32 with wsock32.dll for NetEndian helper stuff.
+  * support StructHelper for FFI::Unions
+  * support passing arguments to StructLayoutBuilder in dsl_layout()
+  * allow overriding copy_size to address incorrect alignment issues in FFI
+
 === 0.1.5 / 2010-1-4
   * Added p_struct dsl directive sugar for creating FFI::Struct accessors to 
     handle pointers to structs.
@@ -5,5 +26,6 @@
 === 0.1.4 / 2010-1-1
   * Support for FFI 0.5.0 final and up.
   * Added NetStructHelper with accessors to provide automatic network byte 
-  order conversion on network packet structures.
+    order conversion on network packet structures.
+
 

data/VERSION

@@ -1 +1 @@
-0.1.5
+0.1.7

data/ffi_dry.gemspec

@@ -1,15 +1,15 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{ffi_dry}
-  s.version = "0.1.5"
+  s.version = "0.1.7"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Eric Monti"]
-  s.date = %q{2010-01-15}
+  s.date = %q{2010-02-05}
   s.description = %q{Provides some useful modules, classes, and methods for FFI bindings  as well as a DSL-like syntax for FFI::Struct layouts}
   s.email = %q{emonti@matasano.com}
   s.extra_rdoc_files = [
@@ -62,3 +62,4 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<yard>, [">= 0"])
   end
 end
+

data/lib/ffi/dry.rb

@@ -131,7 +131,14 @@ module FFI::DRY
     # 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) )
+      self.class.new( :raw => self.to_ptr.read_string(self.copy_size+grown) )
+    end
+
+    # This method is called when creating a copy of self. It can be overridden
+    # by derived structures to return another size. This is sometimes done
+    # to account for alignment issues, etc.
+    def copy_size
+      self.size
     end
 
     # Returns a pointer to the specified field, which is the name assigned
@@ -150,19 +157,33 @@ module FFI::DRY
         @dsl_metadata
       end
 
-      private
+      def define_field_accessor name, &block
+        if instance_methods.include?("#{name}")
+          warn "WARNING: The name '#{name}' is in use for class #{self} "+
+               "Skipping automatic method creation in dsl_layout block."
+        else
+          define_method name, &block
+        end
+      end
 
       # This passes a block to an instance of DSLStructLayoutBuilder, allowing
-      # for a more declarative syntax with extra metadata.
+      # for a more declarative syntax with additional metadata to be included.
       #
-      # It is a replacement to layout() and stores the dsl_metadata gathered
-      # about structure members locally.
+      # dsl_layout() a replacement to layout() and stores the dsl_metadata 
+      # gathered about structure members locally and automatically creates
+      # accessor methods for each field in the structure.
+      #
+      # NOTE if a structure field name conflicts with another instance method 
+      # already defined in the class, the relevant accessor method is not 
+      # created and a warning is issued. This does not apply to methods
+      # defined after the dsl_layout block is called. In other words this
+      # does not affect the overriding of accessor methods in any way.
       def dsl_layout &block
         builder = DSLStructLayoutBuilder.new(self)
         builder.instance_eval(&block)
-        @layout = builder.build
+        @layout = self.layout(*(builder.__layout_args))
         @size = @layout.size
-        _class_meths_from_dsl_metadata( builder.metadata )
+        _class_meths_from_dsl_metadata( builder.__metadata )
         return @layout
       end
 
@@ -170,19 +191,15 @@ module FFI::DRY
         (@dsl_metadata = meta).each do |spec|
           name = spec[:name]
           ftype = spec[:type]
-          unless instance_methods.include?(:"#{name}")
-            if p=spec[:p_struct] and p.kind_of?(Class)
-              define_method(:"#{name}") do
-                p.new(self[name]) unless self[name].null?
-              end
-            else
-              define_method(:"#{name}") { self[name] }
+          if p=spec[:p_struct] and p.kind_of?(Class)
+            define_field_accessor(:"#{name}") do
+              p.new(self[name]) unless self[name].null?
             end
+          else
+            define_field_accessor(:"#{name}") { self[name] }
           end
 
-          unless instance_methods.include?(:"#{name}=")
-            define_method(:"#{name}=") {|val| self[name]=val }
-          end 
+          define_field_accessor(:"#{name}=") {|val| self[name]=val }
         end
       end
     end
@@ -191,73 +208,29 @@ module FFI::DRY
       base.extend(ClassMethods)
     end
 
-    alias inspect_orig inspect
-
-    # Overrides inspect to show field names and values
-    def inspect
-      ret = "#<#{self.class}"
-      if not @_inspecting_in_progress
-        @_inspecting_in_progress = true
-        ret << " " << members.map {|m| "#{m}=#{self[m].inspect}"}.join(', ')
-        @_inspecting_in_progress = nil
-      end
-      ret << ">"
-    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.
-  #
+  # This class provides the DSL for StructHelper.dsl_layout.
+  # You probably don't want to use this directly but if you do, to use the DSL,
+  # you may either pass a structure definition into 'instance_eval' or 
+  # call methods on the object. The methods __metadata and __layout_args return
+  # structure information back to the caller, which can use them to create
+  # a new structure.
   class DSLStructLayoutBuilder
-    attr_reader :builder, :metadata
+    attr_reader :__metadata, :__layout_args
 
-    # Initializes the builder with a reference to the structure using it
-    # Instead of duplicating Struct features, we just call back to them.
+    # Initializes the a new builder class. 
     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
+      @__layout_args = []
+      @__metadata = []
+      yield self if block_given?
     end
 
     # A pointer to a structure. The structure does not allocate the entire
-    # space for the structure, just a pointer. When calling the accessors for
-    # a p_struct field, a new instance of the FFI::Struct will be returned.
+    # space for the structure pointed to, just a pointer. When calling the 
+    # accessor for a p_struct field, a new instance of the FFI::Struct type
+    # for the pointer will be returned.
     def p_struct(name, klass, o={})
       unless klass.kind_of?(Class)
         raise(::ArgumentError, "klass must be a Class")
@@ -267,67 +240,54 @@ module FFI::DRY
       field(name, :pointer, opts)
     end
 
-    # Calls StructLayoutBuider.add_array() on the builder and stores 
-    # a metadata hash entry (the opts hash with name and type overridden)
+    # Declaratively adds a field to the structure.
     #
     # Syntax:
     #
-    #   array field_name, [ctype, N], { ... metadata ... }
+    #   field field_name, ctype, { ... 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
-
+    def field(name, type, o={})
       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
+      @__layout_args << name
+      @__layout_args << type
+      @__layout_args << offset if offset
+
+      @__metadata << opts
+      return opts
     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={})
+    alias array field
+    alias struct field
+    alias union field
+
+    # Experimental - Allows specifying structure fields by taking a missing 
+    # method name as field name for the structure.
+    def method_missing(name, type, *extra)
+      o={}
+      if extra.size > 1
+        raise(ArgumentError, 
+          "Bad field definition. Use: name :type, {optional extra parameters}")
+      elsif h=extra.first
+        if h.kind_of? Hash
+          o=h
+        else
+          raise(ArgumentError, "Options must be provided as a hash.")
+        end
+      end
       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
 
-    # This is a support method used similarly as in the actual builder.
-    # XXX Note, as of 0.5.0-final, this became a protected method in the 
-    # FFI builder. We probably need to figure out another, *supported*, way to 
-    # do this without meddling into back-end FFI implementations.
-    def find_type(*args)
-      @pbind.instance_eval { find_type(*args) }
-    end
+      @__layout_args << name
+      @__layout_args << type
+      @__layout_args << offset if offset
 
-    # This is a support method used similarly as in the actual builder.
-    # XXX Note, as of 0.5.0-final, this became a protected method in the 
-    # FFI builder. We probably need to figure out another, *supported*, way to 
-    # do this without meddling into back-end FFI implementations.
-    def enclosing_module(*args)
-      @pbind.instance_eval { enclosing_module(*args) }
+      @__metadata << opts
+      return opts
     end
-
-  end
+  end # DSLStructLayoutBuilder
 
   # ConstMap can be used to organize and lookup value to constant mappings and
   # vice versa. Constants can be imported from a namespace based on a regular
@@ -362,25 +322,24 @@ module FFI::DRY
       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
+    # 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
+  end # ConstMap
 
   # Behaves just like ConstFlags, except that it returns a list
   # of names for the flags. Name string lookups work same way as 
@@ -411,12 +370,17 @@ module FFI::DRY
         list[arg.to_s.upcase]
       end
     end
-  end
+  end # ConstFlagsMap
 
 
   module NetEndian
     extend ::FFI::Library
 
+    begin
+      ffi_lib 'wsock32'
+    rescue LoadError
+    end
+
     attach_function :htons, [:uint16], :uint16
     attach_function :ntohs, [:uint16], :uint16
     attach_function :htonl, [:uint32], :uint32
@@ -431,7 +395,7 @@ module FFI::DRY
       ::FFI.find_type(:int32)  => I32_convert,
       ::FFI.find_type(:uint32) => I32_convert,
     }
-  end
+  end # NetEndian
 
 
   # A special helper for network packet structures that use big-endian or
@@ -440,8 +404,12 @@ module FFI::DRY
   # for 'reading' a 16/32 bit field, and htons/htonl for writing to one.
   #
   # NOTE this helper does not currently do anything special for 64-bit or
-  # higher values.
+  # higher values but this might be added at some point if the need arises.
   #
+  # NOTE unlike the StructHelper module, no special relevance is given
+  # to fields with a ":p_struct" option or defined with the p_struct DSL 
+  # method.  These are ignored and treated like any other field. A net struct 
+  # generally doesn't contain pointers into native memory anyway.
   module NetStructHelper
     def self.included(base)
       base.instance_eval { include StructHelper }
@@ -460,31 +428,18 @@ module FFI::DRY
           # Create endian swapper accessors methods for each applicable
           # field
           if( type.kind_of?(Symbol) and 
-              cnv=NetEndian::ENDIAN_METHS[ ::FFI.find_type(type) ] )
-
-            unless instance_methods.include?(:"#{name}")
-              define_method(:"#{name}"){ cnv[0].call(self[name]) }
-            end
-            unless instance_methods.include?(:"#{name}=")
-              define_method(:"#{name}="){|val| self[name] = cnv[1].call(val) }
-            end
-
+            cnv=NetEndian::ENDIAN_METHS[ ::FFI.find_type(type) ] )
+            define_method(:"#{name}"){ cnv[0].call(self[name]) }
+            define_method(:"#{name}="){|val| self[name] = cnv[1].call(val) }
           else
-
-            unless instance_methods.include?(:"#{name}")
-              define_method(:"#{name}"){ self[name] } 
-            end
-            unless instance_methods.include?(:"#{name}=")
-              define_method(:"#{name}="){|val| self[name]=val }
-            end 
-
+            define_field_accessor(:"#{name}"){ self[name] } 
+            define_field_accessor(:"#{name}="){|val| self[name]=val }
           end
 
         end
       end
     end
-  end
-
-end
+  end # NetStructHelper
 
+end # FFI::DRY
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ffi_dry
 version: !ruby/object:Gem::Version 
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors: 
 - Eric Monti
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-15 00:00:00 -06:00
+date: 2010-02-05 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency