nice-ffi 0.2 → 0.3

data/ChangeLog.txt

@@ -1,3 +1,53 @@
+------------------------------------------------------------
+Author: John Croisant <jacius@gmail.com>
+Date:   Sun Jan 17 21:04:08 2010 -0600
+
+    Nice-FFI 0.3 released.
+
+------------------------------------------------------------
+Author: John Croisant <jacius@gmail.com>
+Date:   Sun Jan 17 20:53:30 2010 -0600
+
+    Updated version and copyright dates.
+
+M	README.rdoc
+M	lib/nice-ffi/pathset.rb
+M	lib/nice-ffi/struct.rb
+M	nice-ffi.gemspec
+
+------------------------------------------------------------
+Author: John Croisant <jacius@gmail.com>
+Date:   Sun Jan 17 20:53:05 2010 -0600
+
+    Fixed AutoPointer errors in opaquestruct_spec.rb.
+
+M	spec/opaquestruct_spec.rb
+
+------------------------------------------------------------
+Author: John Croisant <jacius@gmail.com>
+Date:   Sun Jan 17 20:14:06 2010 -0600
+
+    Struct creates Buffer instead of MemoryPointer.
+
+M	lib/nice-ffi/struct.rb
+
+------------------------------------------------------------
+Author: John Croisant <jacius@gmail.com>
+Date:   Mon Jan 11 15:35:01 2010 -0600
+
+    Improved filename globs for Pathset::DEFAULT.
+
+M	docs/usage.rdoc
+M	lib/nice-ffi/pathset.rb
+
+------------------------------------------------------------
+Author: John Croisant <jacius@gmail.com>
+Date:   Thu Dec 10 13:50:24 2009 -0600
+
+    Updated Struct to play well with Buffers.
+
+M	lib/nice-ffi/struct.rb
+
 ------------------------------------------------------------
 Author: John Croisant <jacius@gmail.com>
 Date:   Sat Oct 24 15:58:31 2009 -0500

data/README.rdoc

@@ -1,12 +1,12 @@
 
 = Nice-FFI
 
-Version::    0.2
-Date::       2009-10-24
+Version::    0.3
+Date::       2010-01-17
 
 Homepage::   http://github.com/jacius/nice-ffi/
 Author::     John Croisant <jacius@gmail.com>
-Copyright::  2009  John Croisant
+Copyright::  2009-2010  John Croisant
 
 
 == Description
@@ -54,7 +54,7 @@ match the new API, then you should wait until version 1.0.
 
 == Requirements
 
-* Ruby-FFI  >= 0.4.0 (or compatible FFI implementation)
+* Ruby-FFI  >= 0.5.0 (or compatible FFI implementation)
 
 
 == Usage
@@ -66,7 +66,7 @@ See docs/usage.rdoc for usage information.
 
 Nice-FFI is licensed under the following terms (the "MIT License"):
 
-Copyright (c) 2009 John Croisant
+Copyright (c) 2009-2010 John Croisant
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/docs/usage.rdoc

@@ -62,12 +62,15 @@ library in likely directories. Specifically, it looks for:
   }
   
   files = {
-    /linux|bsd/  => [ "lib[NAME].so" ],
+    /linux|bsd/  => [ "lib[NAME].so*",
+                      "lib[NAME]-*.so*" ],
   
     /darwin/     => [ "lib[NAME].dylib",
+                      "lib[NAME]-*.dylib",
                       "[NAME].framework/[NAME]" ],
   
-    /windows/    => [ "[NAME].dll" ]
+    /windows/    => [ "[NAME].dll",
+                      "[NAME]-*.dll"]
   }
   
   NiceFFI::PathSet::DEFAULT = NiceFFI::PathSet.new( paths, files )

data/lib/nice-ffi/pathset.rb

@@ -4,7 +4,7 @@
 #
 # Nice-FFI - Convenience layer atop Ruby-FFI
 #
-# Copyright (c) 2009 John Croisant
+# Copyright (c) 2009-2010 John Croisant
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -579,12 +579,15 @@ paths = {
 }
 
 files = {
-  /linux|bsd/  => [ "lib[NAME].so" ],
+  /linux|bsd/  => [ "lib[NAME].so*",
+                    "lib[NAME]-*.so*" ],
 
   /darwin/     => [ "lib[NAME].dylib",
+                    "lib[NAME]-*.dylib",
                     "[NAME].framework/[NAME]" ],
 
-  /windows/    => [ "[NAME].dll" ]
+  /windows/    => [ "[NAME].dll",
+                    "[NAME]-*.dll"]
 }
 
 # The default paths to look for libraries. See PathSet 

data/lib/nice-ffi/struct.rb

@@ -4,7 +4,7 @@
 #
 # Nice-FFI - Convenience layer atop Ruby-FFI
 #
-# Copyright (c) 2009 John Croisant
+# Copyright (c) 2009-2010 John Croisant
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -265,7 +265,7 @@ class NiceFFI::Struct < FFI::Struct
       else
         self.class_eval do
           define_method( member ) do
-            return nil if self.pointer.null?
+            return nil if self.pointer.null? rescue NoMethodError
             return self[member]
           end
         end
@@ -338,23 +338,23 @@ class NiceFFI::Struct < FFI::Struct
     case val
 
     when Hash
-      super()                       # Create empty struct
+      super(FFI::Buffer.new(size))
       init_from_hash( val )         # Read the values from a Hash.
 
     # Note: plain "Array" would mean FFI::Struct::Array in this scope.
     when ::Array
-      super()                       # Create empty struct
+      super(FFI::Buffer.new(size))
       init_from_array( val )        # Read the values from an Array.
 
     when String
-      super()                       # Create empty struct
+      super(FFI::Buffer.new(size))
       init_from_bytes( val )        # Read the values from a bytestring.
 
     when self.class
-      super()                         # Create empty struct
+      super(FFI::Buffer.new(size))
       init_from_bytes( val.to_bytes ) # Read the values from another instance.
 
-    when FFI::Pointer
+    when FFI::Pointer, FFI::Buffer
       val = _make_autopointer( val, options[:autorelease] )
 
       # Normal FFI::Struct behavior to wrap the pointer.
@@ -428,8 +428,11 @@ class NiceFFI::Struct < FFI::Struct
 
 
   def to_s
-    if self.pointer.null?
-      return "#<NULL %s:%#.x>"%[self.class.name, self.object_id]
+    begin
+      if self.pointer.null?
+        return "#<NULL %s:%#.x>"%[self.class.name, self.object_id]
+      end
+    rescue NoMethodError
     end
 
     mems = members.collect{ |m|

data/pkg/nice-ffi-0.2/README.rdoc

@@ -0,0 +1,88 @@
+
+= Nice-FFI
+
+Version::    0.2
+Date::       2009-10-24
+
+Homepage::   http://github.com/jacius/nice-ffi/
+Author::     John Croisant <jacius@gmail.com>
+Copyright::  2009  John Croisant
+
+
+== Description
+
+Nice-FFI is a layer on top of Ruby-FFI [1] (and compatible FFI
+systems) with features to ease development of FFI-based libraries.
+
+Nice-FFI currently features:
+
+* NiceFFI::Library: a stand-in for FFI::Library that provides methods
+  for easily finding and loading libraries on any platform, plus
+  automatic wrapping of functions that return struct pointers.
+
+* NiceFFI::PathSet: a class with customizable rules for finding
+  library files on multiple operating system. PathSet is used by
+  NiceFFI::Library.load_library.
+
+* NiceFFI::Struct: a stand-in for FFI::Struct that provides automatic
+  accessors for struct members, optional automatic memory management,
+  more instance initialization options, pretty to_s and inspect
+  methods, and other niceties.
+
+* NiceFFI::OpaqueStruct: a base class for structs with no user-exposed
+  members. Useful when the struct definition is hidden by the
+  underlying C library.
+
+Nice-FFI was originally developed as part of Ruby-SDL-FFI [2].
+
+1. Ruby-FFI: http://github.com/ffi/ffi
+2. Ruby-SDL-FFI: http://github.com/jacius/ruby-sdl-ffi/
+
+
+== Caveats
+
+Nice-FFI is still in EARLY DEVELOPMENT STAGES. That means:
+
+* It may not work correctly (or at all).
+* It may not be complete.
+* It may change drastically with no advanced notice.
+
+As such, this library is currently FOR THE ADVENTUROUS ONLY.
+If you are not willing to continuously update your code to
+match the new API, then you should wait until version 1.0.
+
+
+== Requirements
+
+* Ruby-FFI  >= 0.4.0 (or compatible FFI implementation)
+
+
+== Usage
+
+See docs/usage.rdoc for usage information.
+
+
+== License
+
+Nice-FFI is licensed under the following terms (the "MIT License"):
+
+Copyright (c) 2009 John Croisant
+
+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/pkg/nice-ffi-0.2/TODO.rdoc

@@ -0,0 +1,16 @@
+
+= TODO
+
+* Struct
+  * Write accessor for nested structs (not struct pointers).
+    See comment in NiceFFI::Struct._make_writer for details.
+
+* Specs
+  * Library         (use a mock for ffi_lib.)
+  * PathSet#find    (use a mock for File.exist?.)
+  * Struct
+  * TypedPointer
+
+* Better documentation comments
+  * Library#attach_function
+  * Library#load_library

data/pkg/nice-ffi-0.2/docs/usage.rdoc

@@ -0,0 +1,361 @@
+= Using Nice-FFI
+
+This is a guide on how to use Nice-FFI's features. It assumes that you
+are already somewhat familiar with Ruby-FFI.
+
+
+== NiceFFI::Library
+
+NiceFFI::Library is a drop-in replacement for FFI::Library. It provides
+improved library finding abilities and support for TypedPointer return
+types for attached functions.
+
+
+In fact, NiceFFI::Library *is* FFI::Library, but with a few extras.
+That means that you can do all the regular FFI::Library stuff as well
+as the stuff described here.
+
+
+=== load_library
+
+NiceFFI::Library.load_library is a more convenient replacement for
+FFI::Library.ffi_lib. It uses NiceFFI::PathSet to search for the
+library in the most likely places, depending on the user's operating
+system. For example, on Linux it would look for "lib[NAME].so" in
+"/usr/lib/" (among others), while on Windows it would look for
+"[NAME].dll" in "C:\windows\system32\".
+
+Using load_library is easy. Just use "extend NiceFFI::Library" instead
+of "extend FFI::Library", and use "load_library" instead of "ffi_lib":
+
+  
+  require 'nice-ffi'
+  
+  module MyLibraryModule
+    extend NiceFFI::Library
+  
+    load_library("SDL")  # look for libSDL.so, SDL.dll, etc.
+  
+    # structs, functions, etc. as usual.
+  
+  end
+  
+
+==== Advanced load_library
+
+As mentioned, load_library uses NiceFFI::PathSet to search for the
+library in likely directories. Specifically, it looks for:
+
+  
+  paths = {
+    /linux|bsd/  => [ "/usr/local/lib/",
+                      "/usr/lib/" ],
+  
+    /darwin/     => [ "/usr/local/lib/",
+                      "/sw/lib/",
+                      "/opt/local/lib/",
+                      "~/Library/Frameworks/",
+                      "/Library/Frameworks/" ],
+  
+    /windows/    => [ "C:\\windows\\system32\\",
+                      "C:\\windows\\system\\" ]
+  }
+  
+  files = {
+    /linux|bsd/  => [ "lib[NAME].so" ],
+  
+    /darwin/     => [ "lib[NAME].dylib",
+                      "[NAME].framework/[NAME]" ],
+  
+    /windows/    => [ "[NAME].dll" ]
+  }
+  
+  NiceFFI::PathSet::DEFAULT = NiceFFI::PathSet.new( paths, files )
+  
+
+The paths hash tells PathSet where to look for libraries, and the
+files hash tells it the format of the library filename itself. The
+string "[NAME]" is replaced with whatever string you pass to
+load_library.
+
+Each key in the hash should be a Regexp that matches an OS name from
+FFI::Platform::OS. As of this writing (October 2009), the list of
+recognized OS names is:
+
+* "darwin" (MacOS X)
+* "freebsd"
+* "linux"
+* "openbsd"
+* "solaris"
+* "windows"
+
+So, if the user is running Linux and you try to load "SDL", it will
+first look for "/usr/local/lib/libSDL.so". If it can't find that, it
+will then look for "/usr/lib/libSDL.so". It would also use those same
+paths for FreeBSD or OpenBSD, because those OS names also match the
+regexp /linux|bsd/.
+
+If the library could not be found in any of the given directories with
+the given file name formats, load_library will just try loading "SDL"
+using ffi_lib (which does some platform-appropriate guesses too). If
+that fails too, LoadError is raised.
+
+If you want to load from a different path, you can make a custom
+PathSet and pass it to load_library:
+
+  
+  libs_dir = File.dirname(__FILE__) + "/libs/"
+  
+  pathset = NiceFFI::PathSet::DEFAULT.prepend( libs_dir )
+  
+  load_library( "SDL", my_pathset )
+  
+
+The above example prepends (adds in front) the new paths so
+that load_library will look for the library in "./libs/" first.
+See PathSet for other useful methods for modifying PathSets.
+
+
+Another advanced usage tip: If a library has several alternative
+names, you can provide an Array of names:
+
+  
+  # It might be called "foo", "foo2", or "Foo".
+  
+  load_library( ["foo", "foo2", "Foo"] )
+  
+
+=== attach_function
+
+NiceFFI::Library#attach_function behaves similarly to
+FFI::Library#attach_function, except it supports TypedPointer return
+values. For example, suppose you have a C function:
+
+  
+  MyStruct *make_my_struct( int x, int y );
+  
+
+This returns a pointer to an instance of MyStruct. With FFI, you'd
+write this to attach it:
+
+  
+  attach_function :make_my_struct, [:int, :int], :pointer
+  
+
+And when you called it, it would return an FFI::Pointer, which you
+would then have to manually wrap every time you called the method:
+
+  
+  ptr = make_my_struct( 1, 2 )
+  mystruct = MyStruct.new( ptr )
+  
+
+With TypedPointer, the wrapping happens automatically. Just attach
+the function with a TypedPointer instead of :pointer:
+
+  
+  attach_function :make_my_struct, [:int, :int], NiceFFI::TypedPointer( MyStruct )
+  
+  # If MyStruct is based on NiceFFI::Struct, you can do this instead:
+  
+  attach_function :make_my_struct, [:int, :int], MyStruct.typed_pointer
+
+
+Then you automatically get a MyStruct instance when you call the function:
+
+  
+  mystruct = make_my_struct( 1, 2 )
+  mystruct.instance_of?( MyStruct )   # =>  Heck yeah it sure is!
+  
+
+Voila!
+
+
+== NiceFFI::Struct
+
+NiceFFI::Struct is a replacement for FFI::Struct. It provides several
+features in addition to the normal FFI::Struct behavior:
+
+* Ability to construct new instances from Array, Hash, another instance,
+  or a pointer as usual.
+* Automatic read and write accessors for struct members.
+* Accessors for struct pointer members with TypedPointer.
+* Ability to dump an instance as an Array (#to_ary) or Hash (#to_hash).
+* Pretty and useful #to_s and #inspect for debugging.
+
+
+=== Constructors
+
+NiceFFI::Struct allows you to construct a new struct instance from
+a Hash, Array, or another existing instance of the same struct type.
+It can also accept a pointer, just as with FFI::Struct.
+
+  
+  class MyStruct < NiceFFI::Struct
+    layout :x, :int,
+           :y, :int
+  end
+
+  mystruct  = MyStruct.new( {:x => 1, :y => 2} )  # from Hash
+  mystruct2 = MyStruct.new( [1,2] )               # from Array
+  mystruct3 = MyStruct.new( mystruct )            # from another instance
+  mystruct4 = MyStruct.new( ptr )                 # from Pointer
+  
+
+=== Struct Member Accessors
+
+Struct members are defined automatically when you use
+NiceFFI::Struct.layout:
+
+  
+  class MyStruct < NiceFFI::Struct
+    layout :x, :int,
+           :y, :int
+  end
+
+  mystruct = MyStruct.new({:x => 1, :y => 2})
+
+  mystruct.x  # => 1
+  mystruct.y  # => 2
+
+  mystruct.x =  3
+  mystruct.y = -4
+  
+
+Sometimes a struct will have members that should be read-only,
+or completely hidden. In those cases, you can use 
+NiceFFI::Struct.read_only and NiceFFI::Struct.hidden.
+
+  
+  class MySneakyStruct < NiceFFI::Struct
+    layout :readme,  :int,
+           :readme2, :int,
+           :hideme,  :pointer,
+           :hideme2, :pointer,
+           :normal,  :uint32
+  
+    read_only :readme, :readme2
+    hidden    :hideme, :hideme2
+  end
+  
+  sneaky = MySneakyStruct.new( ... )
+  
+
+read_only prevents a write accessor from being created (or removes
+it if there is already one). hidden does the same, but for both
+read and write accessors. hidden also prevents the member from
+being shown in #to_s and #inspect.
+
+read_only and hidden can go before or after layout (or both),
+and you can safely call them multiple times if you need to.
+
+
+=== TypedPointer Struct Member Accessors
+
+Some struct members are :pointers that point to other structs.
+With FFI::Struct, you'd have to manually wrap and unwrap the
+struct pointer, but if you specify a TypedPointer instead of
+:pointer, NiceFFI::Struct will wrap and unwrap it automatically:
+
+  
+  class StructWithPtr < NiceFFI::Struct
+    layout :x,  :int,
+           :y,  :int,
+           :my, NiceFFI::TypedPointer( MyStruct )
+  end
+  
+  struct = StructWithPtr.new( :x  => -1,
+                              :y  => -2,
+                              :my => MyStruct.new([1,2]) )
+  
+  # Seamlessly wraps the pointer in a struct
+  struct.my.kind_of? MyStruct           # true
+  
+  # Seamlessly unwraps the struct and stores the pointer  
+  struct.my = MyStruct.new([-4,-3])
+  
+
+=== Automatic Memory Managment
+
+Ruby-FFI already provides automatic memory management when you create
+a FFI::MemoryPointer or FFI::Buffer instance. When those instances are
+garbage collected, their memory is automatically released so it can be
+used elsewhere.
+
+That feature is used by NiceFFI::Struct when you create a new instance
+by passing a Hash, Array, String, or another instance. In those cases,
+new memory is allocated for the struct instance, and automatically
+released when the struct instance is galbage collected.
+
+NiceFFI::Struct also provides an optional automatic memory management
+system for normal pointers. To use this system, define a "release"
+class method in your class. Then if you create a new struct instance
+with an FFI::Pointer, the release class method will automatically be
+called when the memory for a struct instance needs to be freed.
+
+(This also applies to attached functions with TypedPointer return
+values. The pointers returned from those functions are wrapped in the
+struct class, so if you have defined the release class method, they
+will be automatically memory managed.)
+
+The release class method must accept an FFI::Pointer and call an
+appropriate function to free the struct's memory. Here's an example
+from Ruby-SDL-FFI:
+
+  
+  class Surface < NiceFFI::Struct
+  
+    def self.release( pointer )
+      SDL.FreeSurface( pointer )
+    end
+  
+    # ...
+  
+  end
+  
+
+Note: the release class method should not have any side effects
+besides freeing the struct's memory. Don't be clever!
+
+The memory management system keeps a reference count for each pointer
+address, so the release class method will only be called when all
+struct instances that are using that memory have been garbage
+collected. That means it's safe to have many instances sharing the
+same memory.
+
+If you want to create an instance that doesn't use the memory
+management system, you can disable the :autorelease option when
+creating the instance, like so:
+
+  
+  struct = MyStructClass.new( a_pointer, :autorelease => false )
+  
+
+== NiceFFI::OpaqueStruct
+
+Some C libraries have structs with no publicly-visible layout.
+Instead, the internal details are hidden, and only modified by calling
+functions in the library.
+
+For example, the SDL_mixer library has this definition in its header
+file:
+
+  
+  typedef struct _Mix_Music Mix_Music;
+  
+
+"_Mix_Music" is a struct that is defined within SDL_mixer, but its
+internals are different depending on what features SDL_mixer was
+compiled with. The struct members are not revealed in the header file,
+so they can't be accessed like a normal struct.
+
+NiceFFI provides a class for handling special cases like this,
+NiceFFI::OpaqueStruct. OpaqueStruct has no layout and no members, and
+cannot be created by passing in Hashes, Arrays, etc. It simply holds a
+pointer to the struct memory. As with NiceStruct (and FFI::Struct),
+instances of OpaqueStruct-based classes can be passed directly to
+functions expecting a pointer of the appropriate struct type.
+
+OpaqueStruct features the same optional memory management system as
+NiceStruct. Read the "Automatic Memory Management" section above for
+information about how to use this feature.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: nice-ffi
 version: !ruby/object:Gem::Version 
-  version: "0.2"
+  version: "0.3"
 platform: ruby
 authors: 
 - John Croisant
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-24 00:00:00 -05:00
+date: 2010-01-17 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -34,6 +34,9 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- pkg/nice-ffi-0.2/docs/usage.rdoc
+- pkg/nice-ffi-0.2/TODO.rdoc
+- pkg/nice-ffi-0.2/README.rdoc
 - docs/usage.rdoc
 - TODO.rdoc
 - README.rdoc