emonti-ffi_dry 0.1.0 → 0.1.1

data/README.rdoc

@@ -10,8 +10,9 @@ things and add support for some uncommon ones.
 
 == Synopsis
 
+(samples/ in the package for code)
 
-One major feature is a 'dsl'-like syntax for declaring structure members
+A major feature is a DSL"-like" syntax for declaring structure members
 in FFI::Struct or FFI::ManagedStruct definitions.
     
     require 'rubygems'
@@ -22,27 +23,32 @@ in FFI::Struct or FFI::ManagedStruct definitions.
       include FFI::DRY::StructHelper
 
       # we get a new way of specifying layouts with a 'dsl'-like syntax
-      # The :desc => ... part is arbitrary and can be used however we like.
+      # 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.
+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
+    #...
 
-And we get free additional ways of instantiating and declaring values during 
-initialization. (The FFI standard ways still work too)
+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"
 
@@ -55,10 +61,19 @@ initialization. (The FFI standard ways still work too)
       ss1, 
       ss2, 
       ss3, 
-      ss4].each_with_index {|x,i| p ["ss#{i}",[x.field1, x.field2]]}
+      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 an example which utilizes that arbitrary ':desc' parameter in a 
-"neighborly" way.
+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'
@@ -68,7 +83,7 @@ Here's an example which utilizes that arbitrary ':desc' parameter in a
       include ::FFI::DRY::StructHelper
 
       def self.describe
-        print "Struct: #{self.class}"
+        print "Struct: #{self.name}"
         dsl_metadata().each_with_index do |spec, i|
           print "  Field #{i}\n"
           print "    name:  #{spec[:name].inspect}\n"
@@ -96,7 +111,8 @@ Here's an example which utilizes that arbitrary ':desc' parameter in a
             :desc => "a string up to 255 bytes bound by :len"
       end
 
-      # override kind getter method
+      # 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
@@ -105,16 +121,78 @@ Here's an example which utilizes that arbitrary ':desc' parameter in a
     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
+    ## 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
+    ## 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.
+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'
@@ -122,29 +200,34 @@ and handy thing when porting various libraries.
     module AddressFamily
       include FFI::DRY::ConstMap
       slurp_constants ::Socket, "AF_"
-      def list ; @@list ||= super() ; end
+      def list ; @@list ||= super() ; end  # only generate the hash once
     end
 
-AddressFamily now has all the constants it found for Socket::AF_*
+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 and value lookups using []
+We can do type or value lookups using []
+
     AddressFamily[2]      # => "INET"
     AddressFamily["INET"] # => 2
     
-We can get a hash of all key-value pairs with .list
+We can get a hash of all constant->value pairs with .list
+
     AddressFamily.list
     # => {"NATM"=>31, "DLI"=>13, "UNIX"=>1, "NETBIOS"=>33,  ...}
 
-... which can be inverted for a reverse mapping
+... and invert for a reverse mapping
+
     AddressFamily.list.invert
     # => {16=>"APPLETALK", 5=>"CHAOS", 27=>"NDRV", 0=>"UNSPEC", ...}
 
 
-== Copyright
+== License
 
 Copyright (c) 2009 Eric Monti. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/ffi/dry.rb

@@ -217,6 +217,7 @@ module FFI::DRY
     #
     #   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")
@@ -236,6 +237,7 @@ module FFI::DRY
     #
     #   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") 
@@ -256,6 +258,7 @@ module FFI::DRY
     #
     #   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]
@@ -275,8 +278,7 @@ module FFI::DRY
 
   end
 
-  # Used for creating various value <=> constant mapping modules such as 
-  # Ip::Hdr::Proto for IP protocols.
+  # Used for creating various value <=> constant mapping namespace modules.
   module ConstMap
 
     def self.included(klass)
@@ -333,8 +335,8 @@ module FFI::DRY
     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 names for the flags 
-    # present in it.
+    # 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 = []

data/samples/basic.rb

@@ -1,35 +1,55 @@
-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
-  dsl_layout do
-    field   :field1,  :uint16, :desc => 'this is field 1'
-    field   :field2,  :uint16, :desc => 'this is field 2'
-  end
-end
-
-
-ss0=SomeStruct.new
-
-p ss0.dsl_metadata   # we can look at definition metadata
-
-# 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| p ["ss#{i}",[x.field1, x.field2]]}
+#!/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

@@ -1,48 +1,119 @@
-require 'rubygems'
-require 'ffi'
-require 'ffi/dry'
-
-class NeighborlyStruct < ::FFI::Struct
-  include ::FFI::DRY::StructHelper
-
-  def self.describe
-    print "Struct: #{self.class}"
-    dsl_metadata().each_with_index do |spec, i|
-      print "  Field #{i}\n"+
-            "    name:  #{spec[:name].inspect}\n"+
-            "    type:  #{spec[:type].inspect}\n"+
-            "    desc:  #{spec[:desc]}\n\n"
+# 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
-    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
-  def kind
-    [:default, :bar, :baz][ self[:kind] ]
-  end
-end
-
-s1=TestStruct.new
-s2=SomeStruct.new
-
-puts "*"*70
-s1.describe
-puts "*"*70
-s2.describe
+
+    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
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: emonti-ffi_dry
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Eric Monti
@@ -67,6 +67,7 @@ files:
 - spec/spec_helper.rb
 has_rdoc: false
 homepage: http://github.com/emonti/ffi_dry
+licenses: 
 post_install_message: 
 rdoc_options: 
 - --charset=UTF-8
@@ -87,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.2.0
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: Syntactic sugar and helper utilities for FFI