nice-ffi 0.1 → 0.2

data/lib/nice-ffi/opaquestruct.rb

@@ -0,0 +1,109 @@
+#--
+#
+# This file is one part of:
+#
+# Nice-FFI - Convenience layer atop Ruby-FFI
+#
+# 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.
+#
+#++
+
+
+# OpaqueStruct represents a Struct with an unknown layout.
+# This is meant to be used when the C library designer has
+# intentionally hidden the layout (e.g. to prevent user access).
+#
+# Because the size of an OpaqueStruct is unknown, you should
+# only use methods provided by the C library to allocate, modify,
+# or free the struct's memory.
+#
+# OpaqueStruct supports the same memory autorelease system as
+# NiceStruct. Define MyClass.release( pointer ) to call the library
+# function to free the struct, and pass an FFI::Pointer to #new. You
+# can disable autorelease for an individual instance by providing
+# {:autorelease => false} as an option to #new
+#
+class NiceFFI::OpaqueStruct
+  include NiceFFI::AutoRelease
+
+
+  # Returns a NiceFFI::TypedPointer instance for this class.
+  def self.typed_pointer
+    @typed_pointer or (@typed_pointer = NiceFFI::TypedPointer.new(self))
+  end
+
+
+  # Create a new instance of the class, wrapping (not copying!) a
+  # FFI::Pointer. You can pass another instance of this class to
+  # create a new instance wrapping the same pointer.
+  # 
+  # If val is an instance of FFI::Pointer and you have defined
+  # MyClass.release, the pointer will be passed to MyClass.release
+  # when the memory is no longer being used. Use MyClass.release to
+  # free the memory for the struct, as appropriate for your class. To
+  # disable autorelease for this instance, set {:autorelease => false}
+  # in +options+.
+  # 
+  # (Note: FFI::MemoryPointer and FFI::Buffer have built-in memory
+  # management, so MyClass.release is never called for them.)
+  # 
+  def initialize( val, options={} )
+    options = {:autorelease => true}.merge!( options )
+
+    case val
+
+    when self.class
+      initialize( val.pointer, options )
+
+    when FFI::AutoPointer
+      @pointer = val
+
+    when FFI::Pointer
+      if val.is_a? FFI::MemoryPointer or val.is_a? FFI::Buffer
+        raise TypeError, "unsupported pointer type #{val.class.name}"
+      elsif val.null?
+        @pointer = val
+      else
+        @pointer = _make_autopointer( val, options[:autorelease] )
+      end
+
+    else
+      raise TypeError, "cannot create new #{self.class} from #{val.inspect}"
+
+    end
+  end
+
+
+  attr_reader :pointer
+
+  def to_ptr
+    @pointer
+  end
+
+
+  def to_s
+    "#<%s:%#.x>"%[self.class.name, self.object_id]
+  end
+
+  alias :inspect :to_s
+
+end

data/lib/nice-ffi/pathset.rb

@@ -28,45 +28,102 @@
 #++
 
 
-# PathSet is essentially a Hash of { os_regex => path_templates } pairs,
-# rules describing where to look for files (libraries) on each
-# operating system.
+# PathSet is a collection of directory paths and file name templates,
+# used to help NiceFFI find library files. It allows per-operating
+# system paths and file name templates, using regular expressions to
+# match the OS name.
 # 
-# * os_regex is a regular expression that matches FFI::Platform::OS
-#   for the operating system(s) that the path templates are for.
+# Each PathSet holds two hashes, @paths and @files.
 # 
-# * path_templates is an Array of one or more strings describing
-#   a template for where a library might be found on this OS.
-#   The string [NAME] will be replaced with the library name.
-#   So "/usr/lib/lib[NAME].so" becomes e.g. "/usr/lib/libSDL_ttf.so".
+# * The keys for both @paths and @files are regexps that match
+#   FFI::Platform::OS for the operating system(s) that the paths or
+#   file templates apply to.
 # 
-# You can use #append!, #prepend!, #replace!, #remove!, and #clear!
-# to modify the rules, and #find to look for a file with a matching
-# name.
+# * The values of @paths are Arrays of one or more strings describing
+#   a directory for where a library might be found on this OS. So for
+#   example, one pair in @paths might be { /linux|bsd/ =>
+#   ["/usr/local/lib/", "/usr/lib/"] }, which means: "For operating
+#   systems that match the regular expression /linux|bsd/ (e.g.
+#   'linux', 'freebsd', and 'openbsd'), look for libraries first in
+#   the directory '/usr/local/lib/', then in '/usr/lib/'."
+# 
+# * The value of @files are Arrays of one or more strings describing
+#   the possible formats of library names for that operating system.
+#   These are templates -- they should include string "[NAME]",
+#   which will be replaced with the library name. For example,
+#   "lib[NAME].so" would become "libSDL_ttf.so" when searching for the
+#   "SDL_ttf" library.
+# 
+# There are several methods to modify @paths and/or @files. See
+# #append, #prepend, #replace, #remove, and #delete.
+# 
+# Once @paths and @files are set up, use #find to look for a file with
+# a matching name.
+# 
+# NiceFFI::PathSet::DEFAULT is a pre-made PathSet with paths and file
+# name templates for Linux/BSD, Mac (Darwin), and Windows. It is the
+# default PathSet used by NiceFFI::Library.load_library, and you can
+# also use it as a base for custom PathSets.
 # 
 class NiceFFI::PathSet
 
 
-  def initialize( rules={} )
-    @rules = rules
+  def initialize( paths={}, files={} )
+    @paths = {}
+    @files = {}
+    append!( :paths, paths )
+    append!( :files, files )
   end
   
-  attr_reader :rules
+  attr_reader :paths, :files
 
   def dup
-    self.class.new( @rules.dup )
+    self.class.new( @paths.dup, @files.dup )
   end
 
 
-  # Append the new rules to this PathSet. If this PathSet already
-  # has rules for a regex in the new rules, the new rules will be
-  # added after the current rules.
+  # call-seq:
+  #   append( *entries )
+  #   append( option, *entries )
+  # 
+  # Create a copy of this PathSet and append the new paths and/or
+  # files. If the copy already has entries for a given regexp, the
+  # new entries will be added after the current entries.
+  # 
+  # option::  You can optionally give either :paths or :files as the
+  #           first argument to this method. If :paths, only @paths
+  #           will be modified, @files will never be modified. If
+  #           :files, only @files will be modified, @paths will never
+  #           be modified.
   # 
-  # The given rules can be Hashes or existing PathSets; or
-  # Arrays to append the given rules to every existing regex.
+  # entries:: One or more PathSets, Hashes, Arrays, or Strings,
+  #           or any assortment of these types.
   # 
+  # * If given a PathSet, its @paths and @files are appended to the
+  #   copy's @paths and @files (respectively). If option is :paths,
+  #   only @paths is modified. If option is :files, only @files is
+  #   modified.
   # 
-  # Example:
+  # * If given a Hash, it is appended to the copy's @paths, but
+  #   @files is not affected. If option is :files, @files is modified
+  #   instead of @paths.
+  # 
+  # * If given an Array (which should contain only Strings), the array
+  #   contents are appended to the copy's @paths. If option is
+  #   :files, @files is modified instead of @paths.
+  # 
+  # * If given a String, the string is appended to the copy's
+  #   @paths. If option is :files, @files is modified instead of
+  #   @paths.
+  # 
+  # * If given multiple objects, they are handled in order according to
+  #   the above rules.
+  # 
+  # See also #append! for a version of this method which modifies self
+  # instead of making a copy.
+  # 
+  #--
+  # Example (out of date):
   # 
   #   ps = PathSet.new( /a/ => ["liba"],
   #                     /b/ => ["libb"] )
@@ -74,38 +131,70 @@ class NiceFFI::PathSet
   #   ps.append!( /a/ => ["newliba"],
   #               /c/ => ["libc"] )
   #   
-  #   ps.rules
+  #   ps.paths
   #   # => { /a/ => ["liba",
   #   #              "newliba"],        # added in back
   #   #      /b/ => ["libb"],           # not affected
   #   #      /c/ => ["libc"] }          # added
-  # 
-  def append!( *ruleses )
-    ruleses.each do |rules|
-      _modify( rules ) { |a,b|  a + b }
-    end
-    self
+  #++
+  def append( *entries )
+    self.dup.append!( *entries )
   end
 
-  # Like #append!, but returns a copy instead of modifying the original.
-  def append( *ruleses )
-    self.dup.append!( *ruleses )
+  # call-seq:
+  #   append!( *entries )
+  #   append!( option, *entries )
+  # 
+  # Like #append, but modifies self instead of making a copy.
+  def append!( *entries )
+    _modify( *entries ) { |a,b|  a + b }
   end
 
   alias :+  :append
-  alias :<< :append
 
 
-
-  # Prepend the new rules to this PathSet. If this PathSet already
-  # has rules for a regex in the new rules, the new rules will be
-  # added before the current rules.
+  # call-seq:
+  #   prepend( *entries )
+  #   prepend( option, *entries )
+  # 
+  # Creates a copy of this PathSet and prepends the new paths and/or
+  # files. If the copy already has entries for a given regexp, the
+  # new entries will be added before the current entries.
+  # 
+  # option::  You can optionally give either :paths or :files as the
+  #           first argument to this method. If :paths, only @paths
+  #           will be modified, @files will never be modified. If
+  #           :files, only @files will be modified, @paths will never
+  #           be modified.
   # 
-  # The given rules can be Hashes or existing PathSets; or
-  # Arrays to prepend the given rules to every existing regex.
+  # entries:: One or more PathSets, Hashes, Arrays, or Strings,
+  #           or any assortment of these types.
   # 
+  # * If given a PathSet, its @paths and @files are prepended to this
+  #   PathSet's @paths and @files (respectively). If option is :paths,
+  #   only @paths is modified. If option is :files, only @files is
+  #   modified.
+  #
+  # * If given a Hash, it is prepended to the copy's @paths, but
+  #   @files is not affected. If option is :files, @files is modified
+  #   instead of @paths.
   # 
-  # Example:
+  # * If given an Array (which should contain only Strings), the array
+  #   contents are prepended to the copy's @paths. If option is
+  #   :files, @files is modified instead of @paths.
+  # 
+  # * If given a String, the string is prepended to the copy's
+  #   @paths. If option is :files, @files is modified instead of
+  #   @paths.
+  # 
+  # * If given multiple objects, they are handled in order according to
+  #   the above rules.
+  # 
+  # See also #prepend! for a version of this method which modifies self
+  # instead of making a copy.
+  # 
+  #--
+  # Example (out of date):
   # 
   #   ps = PathSet.new( /a/ => ["liba"],
   #                     /b/ => ["libb"] )
@@ -113,38 +202,74 @@ class NiceFFI::PathSet
   #   ps.prepend!( /a/ => ["newliba"],
   #                /c/ => ["libc"] )
   #   
-  #   ps.rules
+  #   ps.paths
   #   # => { /a/ => ["newliba",         # added in front
   #   #              "liba"],
   #   #      /b/ => ["libb"],           # not affected                
   #   #      /c/ => ["libc"] }          # added
-  # 
-  def prepend!( *ruleses )
-    ruleses.each do |rules|
-      _modify( rules ) { |a,b|  b + a }
-    end
-    self
+  #++
+  def prepend( *entries )
+    self.dup.prepend!( *entries )
   end
 
-  # Like #prepend!, but returns a copy instead of modifying the original.
-  def prepend( *ruleses )
-    self.dup.prepend!( *ruleses )
+  # call-seq:
+  #   prepend!( *entries )
+  #   prepend!( option, *entries )
+  # 
+  # Like #prepend, but modifies self instead of making a copy.
+  def prepend!( *entries )
+    _modify( *entries ) { |a,b|  b + a }
   end
 
-  alias :>> :prepend
 
 
-
-  # Override existing rules with the new rules to this PathSet.
-  # If this PathSet already has rules for a regex in the new rules,
-  # the old rules will be discarded and the new rules used instead.
-  # Old rules are kept if their regex doesn't appear in the new rules.
+  # call-seq:
+  #   replace( *entries )
+  #   replace( option, *entries )
+  # 
+  # Creates a copy of this PathSet and overrides existing entries with
+  # the new entries. If the copy already has entries for a regexp
+  # in the new entries, the old entries will be discarded and the new
+  # entries used instead.
+  # 
+  # option::  You can optionally give either :paths or :files as the
+  #           first argument to this method. If :paths, only @paths
+  #           will be modified, @files will never be modified. If
+  #           :files, only @files will be modified, @paths will never
+  #           be modified.
+  # 
+  # entries:: One or more PathSets, Hashes, Arrays, or Strings,
+  #           or any assortment of these types.
+  # 
+  # * If given a PathSet, the copy's @paths and @files with the
+  #   other PathSet's @paths and @files (respectively). Old entries in
+  #   the copy are kept if their regexp doesn't appear in the given
+  #   PathSet. If option is :paths, only @paths is modified. If option
+  #   is :files, only @files is modified.
+  # 
+  # * If given a Hash, entries in the copy's @paths are replaced
+  #   with the new entries, but @files is not affected. Old entries in
+  #   the copy are kept if their regexp doesn't appear in the given
+  #   PathSet. If option is :files, @files is modified instead of
+  #   @paths.
+  # 
+  # * If given an Array (which should contain only Strings), entries
+  #   for every regexp in the copy's @paths are replaced with the
+  #   array contents. If option is :files, @files is modified instead
+  #   of @paths.
+  # 
+  # * If given a String, all entries for every regexp in the copy's
+  #   @paths are replaced with the string. If option is :files, @files
+  #   is modified instead of @paths.
   # 
-  # The given rules can be Hashes or existing PathSets; or
-  # Arrays to replace the given rules for every existing regex.
+  # * If given multiple objects, they are handled in order according to
+  #   the above rules.
   # 
+  # See also #replace! for a version of this method which modifies self
+  # instead of making a copy.
   # 
-  # Example:
+  #--
+  # Example (out of date):
   # 
   #   ps = PathSet.new( /a/ => ["liba"],
   #                     /b/ => ["libb"] )
@@ -152,36 +277,70 @@ class NiceFFI::PathSet
   #   ps.replace!( /a/ => ["newliba"],
   #                /c/ => ["libc"] )
   #   
-  #   ps.rules
+  #   ps.paths
   #   # => { /a/ => ["newliba"],        # replaced
   #   #      /b/ => ["libb"],           # not affected
   #   #      /c/ => ["libc"] }          # added
-  # 
-  def replace!( *ruleses )
-    ruleses.each do |rules|
-      _modify( rules ) { |a,b|  b }
-    end
-    self
+  #++
+  def replace( *entries )
+    self.dup.replace!( *entries )
   end
 
-  # Like #replace!, but returns a copy instead of modifying the original.
-  def replace( *ruleses )
-    self.dup.replace!( *ruleses )
+  # call-seq:
+  #   replace!( *entries )
+  #   replace!( option, *entries )
+  # 
+  # Like #replace, but modifies self instead of making a copy.
+  def replace!( *entries )
+    _modify( *entries ) { |a,b|  b }
   end
 
 
 
-  # Remove the given rules from the PathSet, if it has them.
-  # This only removes the rules that are given, other rules
-  # for the same regex are kept.
+  # call-seq:
+  #   remove( *entries )
+  #   remove( option, *entries )
+  # 
+  # Creates a copy of this PathSet and removes the given entries from
+  # the copy, if it has them. This only removes the entries that are
+  # given, other entries for the same regexp are kept. Regexps with no
+  # entries left afterwards are removed from the PathSet.
+  # 
+  # option::  You can optionally give either :paths or :files as the
+  #           first argument to this method. If :paths, only @paths
+  #           will be modified, @files will never be modified. If
+  #           :files, only @files will be modified, @paths will never
+  #           be modified.
   # 
-  # The given rules can be Hashes or existing PathSets; or
-  # Arrays to remove the given rules from every existing regex.
+  # entries:: One or more PathSets, Hashes, Arrays, or Strings,
+  #           or any assortment of these types.
   # 
-  # Regexes with no rules left are pruned.
+  # * If given a PathSet, entries from its @paths and @files are
+  #   removed from the copy's @paths and @files (respectively). If
+  #   option is :paths, only @paths is modified. If option is :files,
+  #   only @files is modified.
   # 
+  # * If given a Hash, the given entries are removed from this
+  #   PathSet's @paths, but @files is not affected. If option is
+  #   :files, @files is modified instead of @paths.
   # 
-  # Example:
+  # * If given an Array (which should contain only Strings), the array
+  #   contents are removed from the entries for every regexp in this
+  #   PathSet's @paths. If option is :files, @files is modified
+  #   instead of @paths.
+  # 
+  # * If given a String, the string is removed from the entries for
+  #   every regexp in the copy's @paths. If option is :files,
+  #   @files is modified instead of @paths.
+  # 
+  # * If given multiple objects, they are handled in order according to
+  #   the above rules.
+  # 
+  # See also #remove! for a version of this method which modifies self
+  # instead of making a copy.
+  # 
+  #--
+  # Example (out of date):
   # 
   #   ps = PathSet.new( /a/ => ["liba", "badliba"],
   #                     /b/ => ["libb"] )
@@ -190,55 +349,88 @@ class NiceFFI::PathSet
   #               /b/ => ["libb"] )
   #               /c/ => ["libc"] )
   #   
-  #   ps.rules
+  #   ps.paths
   #   # => { /a/ => ["liba"] }          # removed only "badliba".
-  #   #    # /b/ rules were all removed.
-  #   #    # /c/ not affected because it had no old rules anyway.
-  # 
-  def remove!( *ruleses )
-    ruleses.each do |rules|
-      _modify( rules ) { |a,b|  a - b }
-    end
-    self
+  #   #    # /b/ paths were all removed.
+  #   #    # /c/ not affected because it had no old paths anyway.
+  #++
+  def remove( *entries )
+    self.dup.remove!( *entries )
   end
 
-  # Like #remove!, but returns a copy instead of modifying the original.
-  def remove( *ruleses )
-    self.dup.remove!( *ruleses )
+  # call-seq:
+  #   remove!( *entries )
+  #   remove!( option, *entries )
+  # 
+  # Like #remove, but modifies self instead of making a copy.
+  def remove!( *entries )
+    _modify( *entries ) { |a,b|  a - b }
   end
 
   alias :- :remove
 
 
 
-  # Remove all rules for the given regex(es). Has no effect on
-  # regexes that are not given.
+  # call-seq:
+  #   delete( *regexps )
+  #   delete( option, *regexps )
+  # 
+  # Creates a copy of this PathSet and delete all entries from the
+  # copy for the given regexp(s) from @paths and/or @files. Has no
+  # effect on entries for regexps that are not given.
+  # 
+  # option::  You can optionally give either :paths or :files as the
+  #           first argument to this method. If :paths, only @paths
+  #           will be modified, @files will never be modified. If
+  #           :files, only @files will be modified, @paths will never
+  #           be modified.
+  # 
+  # regexps:: One or more Regexps to remove entries for.
   # 
+  # See also #delete! for a version of this method which modifies self
+  # instead of making a copy.
   # 
-  # Example:
+  #--
+  # Example (out of date):
   # 
   #   ps = PathSet.new( /a/ => ["liba"],
   #                     /b/ => ["libb"] )
   #   
   #   ps.delete!( /b/, /c/ )
   #   
-  #   ps.rules
+  #   ps.paths
   #   # => { /a/  => ["liba"] }  # not affected
-  #   #    # /b/ and all rules removed.
-  #   #    # /c/ not affected because it had no rules anyway.
+  #   #    # /b/ and all paths removed.
+  #   #    # /c/ not affected because it had no paths anyway.
+  #++ 
+  def delete( *regexps )
+    self.dup.delete!( *regexps )
+  end
+
+  # call-seq:
+  #   delete!( *regexps )
+  #   delete!( option, *regexps )
   # 
-  def delete!( *regexs )
-    @rules.delete_if { |regex, paths|  regexs.include? regex }
+  # Like #delete, but modifies self instead of making a copy.
+  def delete!( *regexps )
+    case regexps[0]
+    when :paths
+      @paths.delete_if { |regexp, paths|  regexps.include? regexp }
+    when :files
+      @files.delete_if { |regexp, files|  regexps.include? regexp }
+    when Symbol
+      raise( "Invalid symbol option '#{first.inspect}'. " +
+             "Expected :paths or :files." )
+    else
+      @paths.delete_if { |regexp, paths|  regexps.include? regexp }
+      @files.delete_if { |regexp, files|  regexps.include? regexp }
+    end
     self
   end
 
-  # Like #delete!, but returns a copy instead of modifying the original.
-  def delete( *regexs )
-    self.dup.delete!( *regexs )
-  end
 
 
-  # Try to find a file based on the rules in this PathSet.
+  # Try to find a file based on the paths in this PathSet.
   # 
   # *names:: Strings to try substituting for [NAME] in the paths.
   # 
@@ -248,86 +440,154 @@ class NiceFFI::PathSet
   # Raises LoadError if the current operating system did not match
   # any of the regular expressions in the PathSet.
   # 
-  # Examples:
+  #--
+  # Examples (out of date):
   # 
-  #   ps = PathSet.new( /linux/ => ["/usr/lib/lib[NAME].so"],
-  #                     /win32/ => ["C:\\windows\\system32\\[NAME].dll"] )
+  #   ps = PathSet.new( /linux/   => ["/usr/lib/lib[NAME].so"],
+  #                     /windows/ => ["C:\\windows\\system32\\[NAME].dll"] )
   #   
   #   ps.find( "SDL" )
   #   ps.find( "foo", "foo_alt_name" )
-  # 
+  #++
   def find( *names )
-
     os = FFI::Platform::OS
 
-    # Remember the paths that we found.
-    found = []
-
-    # Remember whether any of the search paths included our OS.
-    os_supported = false
+    # Fetch the paths and files for the matching OSes.
+    paths = @paths.collect{ |regexp,ps| regexp =~ os ? ps : [] }.flatten
+    files = @files.collect{ |regexp,fs| regexp =~ os ? fs : [] }.flatten
 
-    # Find the regexs that matches our OS.
-    os_matches = @rules.keys.find_all{ |regex|  regex =~ os }
-
-    # Drat, they are using an unsupported OS.
-    if os_matches.empty?
+    # Drat, they are using an OS with no matches.
+    if paths.empty? and files.empty?
       raise( LoadError, "Your OS (#{os}) is not supported yet.\n" +
              "Please report this and help us support more platforms." )
     end
 
-    os_matches.each do |os_match|
-      # Fetch the paths for the matching OS.
-      paths = @rules[os_match]
-
-      # Fill in for [NAME] and expand the paths.
-      paths = names.collect { |name|
-        paths.collect { |path|
-          File.expand_path( path.gsub("[NAME]", name) )
-        }
-      }.flatten!
-
-      # Delete all the paths that don't exist.
-      paths.delete_if { |path| not File.exist?(path) }
-
-      # Add what's left.
-      found += paths
+    results = paths.collect do |path|
+      files.collect do |file|
+        names.collect do |name|
+          # Concat path and file, fill in for [NAME], and expand.
+          File.expand_path( (path+file).gsub("[NAME]", name) )
+        end
+      end
     end
 
-    return found
+    return results.flatten.select{ |r| File.exist? r }
   end
 
 
   private
 
 
-  def _modify( rules, &block )  # :nodoc:
+  def _modify( *entries, &block )
+    # could be :paths or :files, or perhaps an entry
+    part = entries[0]
+
+    case part
+    when :paths, :files, :default
+      entries = entries[1..-1]
+    when Symbol # other symbols are invalid
+      raise( "Invalid symbol option '#{first.inspect}'. " +
+             "Expected :paths or :files." )
+    else
+      part = :default
+    end
+
+    entries.each do |entry|
+      if entry.kind_of? self.class
+        if part == :default
+          _modify_set( :paths, entry.paths, &block )
+          _modify_set( :files, entry.files, &block )
+        else
+          _modify_set( part, entry.send(part), &block )
+        end
+      else
+        if part == :default
+          _modify_set( :paths, entry, &block )
+        else
+          _modify_set( part, entry, &block )
+        end
+      end
+    end
+
+    return self
+  end
+
+
+  def _modify_set( ours, other, &block )  # :nodoc:
     raise "No block given!" unless block_given?
 
-    case rules
-    when self.class
-      _modify( rules.rules, &block )
+    ours = case ours
+           when :paths;  @paths
+           when :files;  @files
+           else
+             raise( "Invalid symbol option '#{ours.inspect}'. " +
+                    "Expected :paths or :files." )
+           end
+
+    case other
     when Hash
-      rules.each do |regex, paths|
-        _apply_modifier( regex, (@rules[regex] or []), paths, &block )
+      # Apply each of the regexps in `other` to the same regexp in `ours`
+      other.each do |regexp, paths|
+        _apply_modifier( ours, regexp, (ours[regexp] or []), paths, &block )
       end
     when Array
-      @rules.each { |regex, paths|
-        _apply_modifier( regex, paths, rules, &block )
+      # Apply `other` to each of the regexps in `ours`
+      ours.each { |regexp, paths|
+        _apply_modifier( ours, regexp, paths, other, &block )
+      }
+    when String
+      # Apply an Array holding `other` to each of the regexps in `ours`
+      ours.each { |regexp, paths|
+        _apply_modifier( ours, regexp, paths, [other], &block )
       }
     end
   end
 
 
-  def _apply_modifier( regex, a, b, &block ) # :nodoc:
+  def _apply_modifier( ours, regexp, a, b, &block ) # :nodoc:
     raise "No block given!" unless block_given?
 
     result = yield( a, b )
 
     if result == []
-      @rules.delete( regex )
+      ours.delete( regexp )
     else
-      @rules[regex] = result
+      ours[regexp] = result
     end
   end
 
 end
+
+
+
+#--
+# NOTE: If you update these defaults, update doc/usage.rdoc too.
+#++
+
+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" ]
+}
+
+# The default paths to look for libraries. See PathSet 
+# and NiceFFI::Library.load_library.
+# 
+NiceFFI::PathSet::DEFAULT = NiceFFI::PathSet.new( paths, files )