ffi 1.0.9 → 1.0.10

data/lib/ffi/platform/x86_64-netbsd/types.conf

@@ -0,0 +1,126 @@
+rbx.platform.typedef.__int8_t = char
+rbx.platform.typedef.__uint8_t = uchar
+rbx.platform.typedef.__int16_t = short
+rbx.platform.typedef.__uint16_t = ushort
+rbx.platform.typedef.__int32_t = int
+rbx.platform.typedef.__uint32_t = uint
+rbx.platform.typedef.__int64_t = long_long
+rbx.platform.typedef.__uint64_t = ulong_long
+rbx.platform.typedef.__int_least8_t = char
+rbx.platform.typedef.__uint_least8_t = uchar
+rbx.platform.typedef.__int_least16_t = short
+rbx.platform.typedef.__uint_least16_t = ushort
+rbx.platform.typedef.__int_least32_t = int
+rbx.platform.typedef.__uint_least32_t = uint
+rbx.platform.typedef.__int_least64_t = long_long
+rbx.platform.typedef.__uint_least64_t = ulong_long
+rbx.platform.typedef.__int_fast8_t = int
+rbx.platform.typedef.__uint_fast8_t = uint
+rbx.platform.typedef.__int_fast16_t = int
+rbx.platform.typedef.__uint_fast16_t = uint
+rbx.platform.typedef.__int_fast32_t = int
+rbx.platform.typedef.__uint_fast32_t = uint
+rbx.platform.typedef.__int_fast64_t = long_long
+rbx.platform.typedef.__uint_fast64_t = ulong_long
+rbx.platform.typedef.__intptr_t = long
+rbx.platform.typedef.__uintptr_t = ulong
+rbx.platform.typedef.__intmax_t = long_long
+rbx.platform.typedef.__uintmax_t = ulong_long
+rbx.platform.typedef.__register_t = int
+rbx.platform.typedef.__vaddr_t = ulong
+rbx.platform.typedef.__paddr_t = ulong
+rbx.platform.typedef.__vsize_t = ulong
+rbx.platform.typedef.__psize_t = ulong
+rbx.platform.typedef.__clock_t = int
+rbx.platform.typedef.__clockid_t = int
+rbx.platform.typedef.__off_t = long_long
+rbx.platform.typedef.__ptrdiff_t = long
+rbx.platform.typedef.__size_t = ulong
+rbx.platform.typedef.__ssize_t = long
+rbx.platform.typedef.__time_t = int
+rbx.platform.typedef.__timer_t = int
+rbx.platform.typedef.__wchar_t = int
+rbx.platform.typedef.__wint_t = int
+rbx.platform.typedef.__rune_t = int
+rbx.platform.typedef.__wctrans_t = pointer
+rbx.platform.typedef.__wctype_t = pointer
+rbx.platform.typedef.__cpuid_t = ulong
+rbx.platform.typedef.__dev_t = int
+rbx.platform.typedef.__fixpt_t = uint
+rbx.platform.typedef.__gid_t = uint
+rbx.platform.typedef.__id_t = uint
+rbx.platform.typedef.__in_addr_t = uint
+rbx.platform.typedef.__in_port_t = ushort
+rbx.platform.typedef.__ino_t = uint
+rbx.platform.typedef.__key_t = long
+rbx.platform.typedef.__mode_t = uint
+rbx.platform.typedef.__nlink_t = uint
+rbx.platform.typedef.__pid_t = int
+rbx.platform.typedef.__rlim_t = ulong_long
+rbx.platform.typedef.__sa_family_t = uchar
+rbx.platform.typedef.__segsz_t = int
+rbx.platform.typedef.__socklen_t = uint
+rbx.platform.typedef.__swblk_t = int
+rbx.platform.typedef.__uid_t = uint
+rbx.platform.typedef.__useconds_t = uint
+rbx.platform.typedef.__suseconds_t = int
+rbx.platform.typedef.u_char = uchar
+rbx.platform.typedef.u_short = ushort
+rbx.platform.typedef.u_int = uint
+rbx.platform.typedef.u_long = ulong
+rbx.platform.typedef.unchar = uchar
+rbx.platform.typedef.ushort = ushort
+rbx.platform.typedef.uint = uint
+rbx.platform.typedef.ulong = ulong
+rbx.platform.typedef.cpuid_t = ulong
+rbx.platform.typedef.register_t = int
+rbx.platform.typedef.int8_t = char
+rbx.platform.typedef.uint8_t = uchar
+rbx.platform.typedef.int16_t = short
+rbx.platform.typedef.uint16_t = ushort
+rbx.platform.typedef.int32_t = int
+rbx.platform.typedef.uint32_t = uint
+rbx.platform.typedef.int64_t = long_long
+rbx.platform.typedef.uint64_t = ulong_long
+rbx.platform.typedef.u_int8_t = uchar
+rbx.platform.typedef.u_int16_t = ushort
+rbx.platform.typedef.u_int32_t = uint
+rbx.platform.typedef.u_int64_t = ulong_long
+rbx.platform.typedef.quad_t = long_long
+rbx.platform.typedef.u_quad_t = ulong_long
+rbx.platform.typedef.qaddr_t = pointer
+rbx.platform.typedef.vaddr_t = ulong
+rbx.platform.typedef.paddr_t = ulong
+rbx.platform.typedef.vsize_t = ulong
+rbx.platform.typedef.psize_t = ulong
+rbx.platform.typedef.caddr_t = string
+rbx.platform.typedef.daddr_t = int
+rbx.platform.typedef.daddr32_t = int
+rbx.platform.typedef.daddr64_t = long_long
+rbx.platform.typedef.dev_t = int
+rbx.platform.typedef.fixpt_t = uint
+rbx.platform.typedef.gid_t = uint
+rbx.platform.typedef.id_t = uint
+rbx.platform.typedef.ino_t = uint
+rbx.platform.typedef.key_t = long
+rbx.platform.typedef.mode_t = uint
+rbx.platform.typedef.nlink_t = uint
+rbx.platform.typedef.pid_t = int
+rbx.platform.typedef.rlim_t = ulong_long
+rbx.platform.typedef.segsz_t = int
+rbx.platform.typedef.swblk_t = int
+rbx.platform.typedef.uid_t = uint
+rbx.platform.typedef.useconds_t = uint
+rbx.platform.typedef.suseconds_t = int
+rbx.platform.typedef.in_addr_t = uint
+rbx.platform.typedef.in_port_t = ushort
+rbx.platform.typedef.sa_family_t = uchar
+rbx.platform.typedef.socklen_t = uint
+rbx.platform.typedef.clock_t = int
+rbx.platform.typedef.clockid_t = int
+rbx.platform.typedef.size_t = ulong
+rbx.platform.typedef.ssize_t = long
+rbx.platform.typedef.time_t = int
+rbx.platform.typedef.timer_t = int
+rbx.platform.typedef.off_t = long_long
+rbx.platform.typedef.__fd_mask = int

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

@@ -222,7 +222,7 @@ module FFI
       def aligned(alignment = 1)
         @min_alignment = alignment
       end
-      alias_method :align, :aligned
+      alias :align :aligned
 
       def enclosing_module
         begin

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,23 +3,38 @@ 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 = []
       @constants = {}
@@ -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
+    # Access a constant by name.
     def [](name)
       @constants[name].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,6 +98,11 @@ 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}"
 
@@ -115,6 +152,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 +162,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 +175,27 @@ module FFI
       end.join "\n"
     end
 
+    # Add a C include file to calculate constants from.
+    # @param [String] i include file
+    # @return [Array<String>] array of include files (stdio.h is omitted)
     def include(i)
       @includes << i
     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 +205,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 +215,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/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