Nice-FFI 0.3 (and 0.2)

I’ve just released a new version of Nice-FFI, my convenience library for Ruby FFI libraries. You can install the new version with gem install nice-ffi, as usual. Please note that Nice-FFI is still not considered API-stable, so if you aren’t willing to update your code when a new version comes out, you shouldn’t use it until version 1.0.

Version 0.3 has a few changes:

  • The default PathSet has a less restrictive filename search pattern, so it is better at detecting libraries.
  • Struct.new can now accept FFI::Buffers. Buffers are like MemoryPointers, but with improved performance on JRuby in some situations.
  • Struct.new will now create a Buffer instead of a MemoryPointer when you create a new struct instance by value from an array, hash, bytestring, or another struct.

Also, since I never posted an announcement for 0.2, here are the changes for that version:

  • Added automatic memory management to the Struct class, if you define a “release” class method. It can be disabled per-instance by passing :autorelease => false to MyStruct.new.
  • Added new OpaqueStruct class. This class is useful for when the struct layout is not declared in the C library header. It also features automatic memory management like Struct.
  • Added Struct.typed_pointer, as a convenient alternative to TypedPointer.new(MyStruct). You can also pass :autorelease => false to disable memory management for all structs created via that TypedPointer, which is useful when using the TypedPointer as a function return type.
  • Structs can now be dumped to a bytestring (Struct#to_bytes), and also created from a bytestring (by passing a String to Struct.new).
  • Revamped the PathSet class. It now has separate patterns for paths (directories to search) and files (filename patterns), to be more flexible and easy to customize (e.g. you can add a new directory without caring about the filename pattern).
  • Removed Pathset#<< and Pathset#>>. Use append and prepend instead.
  • Renamed Library::DEFAULT_PATHS to PathSet::DEFAULT.
  • Added Library.optional, for when you want to continue loading the library even if a certain function or variable doesn’t exist in the library (e.g. because it’s not defined in old versions). It takes a code block, and will rescue and emit a warning if there is a FFI load error.
  • Also added Library.opt_func, which is the same as doing attach_function within an optional block.
  • Added some convenience aliases in Library: func = attach_function, var = attach_variable.
  • Nice-FFI no longer depends on the “need” library. We don’t need no stinking need!

You can get Nice-FFI:

Please send bug reports and feature requests to the issue tracker on Github.