ffi 1.0.9-x86-mingw32 → 1.0.12.pre-x86-mingw32

data/lib/ffi/pointer.rb

@@ -21,13 +21,20 @@
 require 'ffi/platform'
 module FFI
   class Pointer
+    
+    # Pointer size
     SIZE = Platform::ADDRESS_SIZE / 8
 
     # Return the size of a pointer on the current platform, in bytes
+    # @return [Numeric]
     def self.size
       SIZE
     end
 
+    # @param [nil,Numeric] len length of string to return
+    # @return [String]
+    # Read pointer's contents as a string, or the first +len+ bytes of the 
+    # equivalent string if +len+ is not +nil+.
     def read_string(len=nil)
       if len
         get_bytes(0, len)
@@ -36,24 +43,54 @@ module FFI
       end
     end
 
+    # @param [Numeric] len length of string to return
+    # @return [String]
+    # Read the first +len+ bytes of pointer's contents as a string.
+    #
+    # Same as:
+    #  ptr.read_string(len)  # with len not nil
     def read_string_length(len)
       get_bytes(0, len)
     end
 
+    # @return [String]
+    # Read pointer's contents as a string.
+    #
+    # Same as:
+    #  ptr.read_string  # with no len
     def read_string_to_null
       get_string(0)
     end
 
+    # @param [String] str string to write
+    # @param [Numeric] len length of string to return
+    # @return [self]
+    # Write +len+ first bytes of +str+ in pointer's contents.
+    #
+    # Same as:
+    #  ptr.write_string(str, len)   # with len not nil
     def write_string_length(str, len)
       put_bytes(0, str, 0, len)
     end
 
+    # @param [String] str string to write
+    # @param [Numeric] len length of string to return
+    # @return [self]
+    # Write +str+ in pointer's contents, or first +len+ bytes if 
+    # +len+ is not +nil+.
     def write_string(str, len=nil)
       len = str.bytesize unless len
       # Write the string data without NUL termination
       put_bytes(0, str, 0, len)
     end
 
+    # @param [Type] type type of data to read from pointer's contents
+    # @param [Symbol] reader method to send to +self+ to read +type+
+    # @param [Numeric] length
+    # @return [Array]
+    # Read an array of +type+ of length +length+.
+    # @example
+    #  ptr.write_array_of_type(TYPE_UINT8, :get_uint8, 4) # -> [1, 2, 3, 4]
     def read_array_of_type(type, reader, length)
       ary = []
       size = FFI.type_size(type)
@@ -65,6 +102,13 @@ module FFI
       ary
     end
 
+    # @param [Type] type type of data to write to pointer's contents
+    # @param [Symbol] writer method to send to +self+ to write +type+
+    # @param [Array] ary
+    # @return [self]
+    # Write +ary+ in pointer's contents as +type+.
+    # @example
+    #  ptr.write_array_of_type(TYPE_UINT8, :put_uint8, [1, 2, 3 ,4])
     def write_array_of_type(type, writer, ary)
       size = FFI.type_size(type)
       tmp = self

data/lib/ffi/struct.rb

@@ -123,10 +123,6 @@ module FFI
       @layout.alignment
     end
 
-    def self.align
-      @layout.alignment
-    end
-
     def self.members
       @layout.members
     end
@@ -222,13 +218,13 @@ module FFI
       def aligned(alignment = 1)
         @min_alignment = alignment
       end
-      alias_method :align, :aligned
+      alias :align :aligned
 
       def enclosing_module
         begin
           mod = self.name.split("::")[0..-2].inject(Object) { |obj, c| obj.const_get(c) }
           mod.respond_to?(:find_type) ? mod : nil
-        rescue Exception => ex
+        rescue Exception
           nil
         end
       end

data/lib/ffi/struct_layout_builder.rb

@@ -71,6 +71,7 @@ module FFI
       Type::UINT64,
       Type::FLOAT32,
       Type::FLOAT64,
+      Type::BOOL,
     ]
 
     def add(name, type, offset = nil)
@@ -155,4 +156,4 @@ module FFI
     end
   end
 
-end
+end

data/lib/ffi/tools/const_generator.rb

@@ -3,25 +3,40 @@ require 'open3'
 
 module FFI
 
-  ##
   # ConstGenerator turns C constants into ruby values.
-
+  #
+  # @example a simple example for stdio
+  #  cg = FFI::ConstGenerator.new('stdio') do |gen|
+  #    gen.const(:SEEK_SET)
+  #    gen.const('SEEK_CUR')
+  #    gen.const('seek_end')   # this constant does not exist
+  #  end            # #calculate called automatically at the end of the block
+  #
+  #  cg['SEEK_SET'] # => 0
+  #  cg['SEEK_CUR'] # => 1
+  #  cg['seek_end'] # => nil
+  #  cg.to_ruby     # => "SEEK_SET = 0\nSEEK_CUR = 1\n# seek_end not available"
   class ConstGenerator
     @options = {}
     attr_reader :constants
 
-    ##
     # Creates a new constant generator that uses +prefix+ as a name, and an
     # options hash.
     #
-    # The only option is :required, which if set to true raises an error if a
+    # The only option is +:required+, which if set to +true+ raises an error if a
     # constant you have requested was not found.
-    #
-    # When passed a block, #calculate is automatically called at the end of
-    # the block, otherwise you must call it yourself.
-
+    # 
+    # @param [#to_s] prefix
+    # @param [Hash] options
+    # @return 
+    # @option options [Boolean] :required
+    # @overload initialize(prefix, options)
+    # @overload initialize(prefix, options) { |gen| ... }
+    #  @yieldparam [ConstGenerator] gen new generator is passed to the block
+    #  When passed a block, {#calculate} is automatically called at the end of
+    #  the block, otherwise you must call it yourself.
     def initialize(prefix = nil, options = {})
-      @includes = []
+      @includes = ['stdio.h', 'stddef.h']
       @constants = {}
       @prefix = prefix
 
@@ -33,23 +48,40 @@ module FFI
         calculate self.class.options.merge(options)
       end
     end
+    # Set class options
+    # These options are merged with {#initialize} options when it is called with a block.
+    # @param [Hash] options
+    # @return [Hash] class options
     def self.options=(options)
       @options = options
     end
+    # Get class options.
+    # @return [Hash] class options
     def self.options
       @options
     end
+    # @param [String] name
+    # @return constant value (converted if a +converter+ was defined).
+    # Access a constant by name.
     def [](name)
-      @constants[name].value
+      @constants[name].converted_value
     end
 
-    ##
-    # Request the value for C constant +name+.  +format+ is a printf format
-    # string to print the value out, and +cast+ is a C cast for the value.
-    # +ruby_name+ allows you to give the constant an alternate ruby name for
-    # #to_ruby.  +converter+ or +converter_proc+ allow you to convert the
-    # value from a string to the appropriate type for #to_ruby.
-
+    # Request the value for C constant +name+.
+    #
+    # @param [#to_s] name C constant name
+    # @param [String] format a printf format string to print the value out
+    # @param [String] cast a C cast for the value
+    # @param ruby_name alternate ruby name for {#to_ruby}
+    #
+    # @overload const(name, format=nil, cast='', ruby_name=nil, converter=nil)
+    #  +converter+ is a Method or a Proc.
+    #  @param [#call] converter convert the value from a string to the appropriate
+    #   type for {#to_ruby}.
+    # @overload const(name, format=nil, cast='', ruby_name=nil) { |value| ... }
+    #  Use a converter block. This block convert the value from a string to the 
+    #  appropriate type for {#to_ruby}.
+    #  @yieldparam value constant value
     def const(name, format = nil, cast = '', ruby_name = nil, converter = nil,
               &converter_proc)
       format ||= '%d'
@@ -66,18 +98,19 @@ module FFI
       return const
     end
 
+    # Calculate constants values.
+    # @param [Hash] options
+    # @option options [String] :cppflags flags for C compiler
+    # @return [nil]
+    # @raise if a constant is missing and +:required+ was set to +true+ (see {#initialize})
     def calculate(options = {})
       binary = File.join Dir.tmpdir, "rb_const_gen_bin_#{Process.pid}"
 
       Tempfile.open("#{@prefix}.const_generator") do |f|
-        f.puts "#include <stdio.h>"
-
         @includes.each do |inc|
           f.puts "#include <#{inc}>"
         end
-
-        f.puts "#include <stddef.h>\n\n"
-        f.puts "int main(int argc, char **argv)\n{"
+        f.puts "\nint main(int argc, char **argv)\n{"
 
         @constants.each_value do |const|
           f.puts <<-EOF
@@ -115,6 +148,9 @@ module FFI
       end
     end
 
+    # Dump constants to +io+.
+    # @param [#puts] io
+    # @return [nil]
     def dump_constants(io)
       @constants.each do |name, constant|
         name = [@prefix, name].join '.' if @prefix
@@ -122,10 +158,9 @@ module FFI
       end
     end
 
-    ##
     # Outputs values for discovered constants.  If the constant's value was
     # not discovered it is not omitted.
-
+    # @return [String]
     def to_ruby
       @constants.sort_by { |name,| name }.map do |name, constant|
         if constant.value.nil? then
@@ -136,17 +171,28 @@ module FFI
       end.join "\n"
     end
 
-    def include(i)
-      @includes << i
+    # Add additional C include file(s) to calculate constants from.
+    # @note +stdio.h+ and +stddef.h+ automatically included
+    # @param [List<String>, Array<String>] i include file(s)
+    # @return [Array<String>] array of include files
+    def include(*i)
+      @includes |= i.flatten
     end
 
   end
 
+  # This class hold constants for {ConstGenerator}
   class ConstGenerator::Constant
 
     attr_reader :name, :format, :cast
     attr_accessor :value
 
+    # @param [#to_s] name
+    # @param [String] format a printf format string to print the value out
+    # @param [String] cast a C cast for the value
+    # @param ruby_name alternate ruby name for {#to_ruby}
+    # @param [#call] converter convert the value from a string to the appropriate
+    #  type for {#to_ruby}.
     def initialize(name, format, cast, ruby_name = nil, converter=nil)
       @name = name
       @format = format
@@ -156,6 +202,8 @@ module FFI
       @value = nil
     end
 
+    # Return constant value (converted if a +converter+ was defined).
+    # @return constant value.
     def converted_value
       if @converter
         @converter.call(@value)
@@ -164,10 +212,14 @@ module FFI
       end
     end
 
+    # get constant ruby name
+    # @return [String]
     def ruby_name
       @ruby_name || @name
     end
 
+    # Get an evaluable string from constant.
+    # @return [String]
     def to_ruby
       "#{ruby_name} = #{converted_value}"
     end

data/lib/ffi/tools/types_generator.rb

@@ -51,7 +51,14 @@ module FFI
         C
 
         io.close
-        typedefs = `gcc -E -x c #{options[:cppflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -c #{io.path}`
+        cmd = "gcc -E -x c #{options[:cppflags]} -D_DARWIN_USE_64_BIT_INODE -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -c"
+        if options[:input]
+          typedefs = File.read(options[:input])
+        elsif options[:remote]
+          typedefs = `ssh #{options[:remote]} #{cmd} - < #{io.path}`
+        else
+          typedefs = `#{cmd} #{io.path}`
+        end
       end
       
       code = ""

data/lib/ffi/types.rb

@@ -17,17 +17,29 @@
 # version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
 #
 
+# see {file:README}
 module FFI
 
+  # @param [Type, DataConverter, Symbol] old type definition used by {FFI.find_type}
+  # @param [Symbol] add new type definition's name to add
+  # @return [Type]
+  # Add a definition type to type definitions.
   def self.typedef(old, add)
     TypeDefs[add] = self.find_type(old)
   end
 
+  # (see FFI.typedef)
   def self.add_typedef(old, add)
     typedef old, add
   end
 
 
+  # @param [Type, DataConverter, Symbol] name
+  # @param [Hash] type_map if nil, {FFI::TypeDefs} is used
+  # @return [Type]
+  # Find a type in +type_map+ ({FFI::TypeDefs}, by default) from
+  # a type objet, a type name (symbol). If +name+ is a {DataConverter},
+  # a new {Type::Mapped} is created.
   def self.find_type(name, type_map = nil)
     if name.is_a?(Type)
       name
@@ -46,6 +58,7 @@ module FFI
     end
   end
 
+  # List of type definitions
   TypeDefs.merge!({
       # The C void type; only useful for function return types
       :void => Type::VOID,
@@ -120,11 +133,15 @@ module FFI
       :varargs => Type::VARARGS,
   })
 
-  # Returns a [ String, Pointer ] tuple so the C memory for the string can be freed
+  
   class StrPtrConverter
     extend DataConverter
     native_type Type::POINTER
 
+    # @param [Pointer] val
+    # @param [] ctx
+    # @return [Array(String, Pointer)]
+    # Returns a [ String, Pointer ] tuple so the C memory for the string can be freed
     def self.from_native(val, ctx)
       [ val.null? ? nil : val.get_string(0), val ]
     end
@@ -133,6 +150,9 @@ module FFI
 
   typedef(StrPtrConverter, :strptr)
 
+  # @param type +type+ is an instance of class accepted by {FFI.find_type}
+  # @return [Numeric]
+  # Get +type+ size, in bytes.
   def self.type_size(type)
     find_type(type).size
   end

data/spec/ffi/async_callback_spec.rb

@@ -32,7 +32,7 @@ describe "async callback" do
     cb = Proc.new {|i| v = i; called = true }
     LibTest.testAsyncCallback(cb, 0x7fffffff) 
     called.should be_true
-    v.should == 0x7fffffff
+    v.should eq 0x7fffffff
   end
   
   it "called a second time" do
@@ -41,6 +41,6 @@ describe "async callback" do
     cb = Proc.new {|i| v = i; called = true }
     LibTest.testAsyncCallback(cb, 0x7fffffff) 
     called.should be_true
-    v.should == 0x7fffffff
+    v.should eq 0x7fffffff
   end
 end

data/spec/ffi/bool_spec.rb

@@ -25,14 +25,14 @@ describe "Function with primitive boolean arguments and return values" do
     attach_function :bool_reverse_val, [ :bool ], :bool
   end
   it "bools" do
-    LibTest.bool_return_true.should == true
-    LibTest.bool_return_false.should == false
+    LibTest.bool_return_true.should eq true
+    LibTest.bool_return_false.should eq false
 
-    LibTest.bool_return_val(true).should == true
-    LibTest.bool_return_val(false).should == false
+    LibTest.bool_return_val(true).should eq true
+    LibTest.bool_return_val(false).should eq false
 
-    LibTest.bool_reverse_val(true).should == false
-    LibTest.bool_reverse_val(false).should == true
+    LibTest.bool_reverse_val(true).should eq false
+    LibTest.bool_reverse_val(false).should eq true
   end
   it "raise error on invalid types" do
     lambda { LibTest.bool_return_val(nil) }.should raise_error(::TypeError)

data/spec/ffi/buffer_spec.rb

@@ -23,13 +23,13 @@ describe "Buffer#total" do
       :long_long => 8, :ulong_long => 8, :float => 4, :double => 8
     }.each_pair do |t, s|
       it "Buffer.alloc_in(#{t}, #{i}).total == #{i * s}" do
-        FFI::Buffer.alloc_in(t, i).total.should == i * s
+        FFI::Buffer.alloc_in(t, i).total.should eq i * s
       end
       it "Buffer.alloc_out(#{t}, #{i}).total == #{i * s}" do
-        FFI::Buffer.alloc_out(t, i).total.should == i * s
+        FFI::Buffer.alloc_out(t, i).total.should eq i * s
       end
       it "Buffer.alloc_inout(#{t}, #{i}).total == #{i * s}" do
-        FFI::Buffer.alloc_inout(t, i).total.should == i * s
+        FFI::Buffer.alloc_inout(t, i).total.should eq i * s
       end
     end
   end
@@ -40,7 +40,7 @@ describe "Buffer#put_char" do
   (0..127).each do |i|
     (0..bufsize-1).each do |offset|
       it "put_char(#{offset}, #{i}).get_char(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_char(offset, i).get_char(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_char(offset, i).get_char(offset).should eq i
       end
     end
   end
@@ -50,7 +50,7 @@ describe "Buffer#put_uchar" do
   (0..255).each do |i|
     (0..bufsize-1).each do |offset|
       it "Buffer.put_uchar(#{offset}, #{i}).get_uchar(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_uchar(offset, i).get_uchar(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_uchar(offset, i).get_uchar(offset).should eq i
       end
     end
   end 
@@ -60,7 +60,7 @@ describe "Buffer#put_short" do
   [0, 1, 128, 32767].each do |i|
     (0..bufsize-2).each do |offset|
       it "put_short(#{offset}, #{i}).get_short(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_short(offset, i).get_short(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_short(offset, i).get_short(offset).should eq i
       end
     end
   end
@@ -70,7 +70,7 @@ describe "Buffer#put_ushort" do
   [ 0, 1, 128, 32767, 65535, 0xfee1, 0xdead, 0xbeef, 0xcafe ].each do |i|
     (0..bufsize-2).each do |offset|
       it "put_ushort(#{offset}, #{i}).get_ushort(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_ushort(offset, i).get_ushort(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_ushort(offset, i).get_ushort(offset).should eq i
       end
     end
   end
@@ -80,7 +80,7 @@ describe "Buffer#put_int" do
   [0, 1, 128, 32767, 0x7ffffff ].each do |i|
     (0..bufsize-4).each do |offset|
       it "put_int(#{offset}, #{i}).get_int(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_int(offset, i).get_int(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_int(offset, i).get_int(offset).should eq i
       end
     end
   end
@@ -90,7 +90,7 @@ describe "Buffer#put_uint" do
   [ 0, 1, 128, 32767, 65535, 0xfee1dead, 0xcafebabe, 0xffffffff ].each do |i|
     (0..bufsize-4).each do |offset|
       it "put_uint(#{offset}, #{i}).get_uint(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_uint(offset, i).get_uint(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_uint(offset, i).get_uint(offset).should eq i
       end
     end
   end
@@ -100,7 +100,7 @@ describe "Buffer#put_long" do
   [0, 1, 128, 32767, 0x7ffffff ].each do |i|
     (0..bufsize-FFI::Type::LONG.size).each do |offset|
       it "put_long(#{offset}, #{i}).get_long(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_long(offset, i).get_long(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_long(offset, i).get_long(offset).should eq i
       end
     end
   end
@@ -110,7 +110,7 @@ describe "Buffer#put_ulong" do
   [ 0, 1, 128, 32767, 65535, 0xfee1dead, 0xcafebabe, 0xffffffff ].each do |i|
     (0..bufsize-FFI::Type::LONG.size).each do |offset|
       it "put_ulong(#{offset}, #{i}).get_ulong(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_ulong(offset, i).get_ulong(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_ulong(offset, i).get_ulong(offset).should eq i
       end
     end
   end
@@ -120,7 +120,7 @@ describe "Buffer#put_long_long" do
   [0, 1, 128, 32767, 0x7ffffffffffffff ].each do |i|
     (0..bufsize-8).each do |offset|
       it "put_long_long(#{offset}, #{i}).get_long_long(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_long_long(offset, i).get_long_long(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_long_long(offset, i).get_long_long(offset).should eq i
       end
     end
   end
@@ -130,7 +130,7 @@ describe "Buffer#put_ulong_long" do
   [ 0, 1, 128, 32767, 65535, 0xdeadcafebabe, 0x7fffffffffffffff ].each do |i|
     (0..bufsize-8).each do |offset|
       it "put_ulong_long(#{offset}, #{i}).get_ulong_long(#{offset}) == #{i}" do
-        FFI::Buffer.alloc_in(bufsize).put_ulong_long(offset, i).get_ulong_long(offset).should == i
+        FFI::Buffer.alloc_in(bufsize).put_ulong_long(offset, i).get_ulong_long(offset).should eq i
       end
     end
   end
@@ -141,21 +141,21 @@ describe "Reading/Writing binary strings" do
     buf = FFI::Buffer.new 1024
     buf.put_bytes(0, str);
     s2 = buf.get_bytes(0, 11);
-    s2.should == str
+    s2.should eq str
   end
   it "Buffer#put_bytes with index and length" do
     str = "hello\0world"
     buf = FFI::Buffer.new 1024
     buf.put_bytes(0, str, 5, 6);
     s2 = buf.get_bytes(0, 6);
-    s2.should == str[5..-1]
+    s2.should eq str[5..-1]
   end
   it "Buffer#put_bytes with only index" do
     str = "hello\0world"
     buf = FFI::Buffer.new 1024
     buf.put_bytes(0, str, 5);
     s2 = buf.get_bytes(0, 6);
-    s2.should == str[5..-1]
+    s2.should eq str[5..-1]
   end
   it "Buffer#put_bytes with index > str.length" do
     str = "hello\0world"
@@ -179,21 +179,21 @@ describe "Reading/Writing ascii strings" do
     buf = FFI::Buffer.new 1024
     buf.put_string(0, str);
     s2 = buf.get_bytes(0, 11);
-    s2.should == str
+    s2.should eq str
   end
   it "Buffer#get_string with string containing zero byte" do
     str = "hello\0world"
     buf = FFI::Buffer.new 1024
     buf.put_bytes(0, str);
     s2 = buf.get_string(0, 11);
-    s2.should == "hello"
+    s2.should eq "hello"
   end
   it "Buffer#put_string without length should NUL terminate" do
     str = "hello"
     buf = FFI::Buffer.new 1024
     buf.put_string(0, str);
     s2 = buf.get_bytes(0, 6);
-    s2.should == "hello\0"
+    s2.should eq "hello\0"
   end
 end
 describe "Buffer#put_pointer" do
@@ -203,13 +203,13 @@ describe "Buffer#put_pointer" do
     buf = FFI::Buffer.alloc_inout 8
     p2 = buf.put_pointer(0, p).get_pointer(0)
     p2.should_not be_nil
-    p2.should == p
-    p2.get_uint(0).should == 0xdeadbeef
+    p2.should eq p
+    p2.get_uint(0).should eq 0xdeadbeef
   end
 end
 describe "Buffer#size" do
   it "should return size" do
     buf = FFI::Buffer.new 14
-    buf.size.should == 14
+    buf.size.should eq 14
   end
-end
+end