Class NiceFFI::PathSet
In: lib/nice-ffi/pathset.rb
Parent: Object

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.

Each PathSet holds two hashes, @paths and @files.

  • 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.
  • 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.

Methods

+   -   append   append!   delete   delete!   dup   find   new   prepend   prepend!   remove   remove!   replace   replace!  

Attributes

files  [R] 
paths  [R] 

Public Class methods

Public Instance methods

+( *entries )

Alias for append

-( *entries )

Alias for remove

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.
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.
  • 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.

Like append, but modifies self instead of making a copy.

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.

Like delete, but modifies self instead of making a copy.

Try to find a file based on the paths in this PathSet.

*names:Strings to try substituting for [NAME] in the paths.

Returns an Array of the paths of matching files, or [] if there were no matches.

Raises LoadError if the current operating system did not match any of the regular expressions in the PathSet.

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.
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.
  • 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.

Like prepend, but modifies self instead of making a copy.

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.
entries:One or more PathSets, Hashes, Arrays, or Strings, or any assortment of these types.
  • 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.
  • 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.

Like remove, but modifies self instead of making a copy.

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.
  • 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.

Like replace, but modifies self instead of making a copy.

[Validate]