s11n::plugin::path_finder Class Reference

path_finder searches for keys using a set of prefixes (paths) and suffixes (file extensions). More...

#include <path_finder.hpp>

List of all members.

Public Types

typedef std::list
< std::string > 
string_list
 A list type returned by some functions.

Public Member Functions

 path_finder (const std::string &path=std::string(), const std::string &ext=std::string(), const std::string &pathsep=":")
 Creates object with the given path/extension list.
virtual ~path_finder ()
std::string path_string () const
 Returns a ":"-separated string of all paths added via add/path().
void path_separator (const std::string &sep)
 Sets the string used as a separator for the string-based variants of path(), extentions(), etc.
const std::string & path_separator () const
 Returns the path separator string.
virtual std::size_t path (const std::string &p)
 Sets the path to p, which should be a path_separator()-delimited string.
virtual std::size_t path (const string_list &p)
 Sets the path to the given list of directories.
virtual void add_path (const std::string &p)
 Adds p to the path.
virtual void add_extension (const std::string &ext=std::string())
 Adds a "search extension." Sample: finder.extension( ".txt:.TXT" ); Will now try all path combinations with the rightmost characters matching ".txt" or ".TXT" (in that order).
virtual std::size_t extensions (const std::string &ext)
 like add_extension(), but overwrites extension list.
virtual std::size_t extensions (const string_list &p)
 Sets the extensions list to the given list.
std::string extensions_string () const
 Returns the path_separator()-delimited listed of file suffixes to use when searching for a path.
const string_listextensions () const
 Returns this object's extensions list.
string_listextensions ()
 Non-const overload, intended for serialization.
std::string find (const std::string &resourcename, bool check_cache=true) const
 Returns the full path of the given resource, provided it could be found using the available lookup paths/extensions and is readable.
void clear_cache ()
 Empties the hit-cache used by find().
const string_listpath () const
 Returns a list of all items added via add_path() and path().
string_listpath ()
 Non-const overload, intended for serialization.
bool empty () const
 Returns true if this object has no paths or extensions.

Static Public Member Functions

static std::string join_list (const string_list &list, const std::string &separator)
 Helper function to collapse a list into a string.
static bool is_accessible (const std::string &path)
 Returns true if path is readable.
static std::string basename (const std::string &)
 Returns the "base name" of the given string: any part following the final directory separator character.
static std::string dir_separator ()
 Returns a platform-dependent path separator.


Detailed Description

path_finder searches for keys using a set of prefixes (paths) and suffixes (file extensions).

Example:

           path_finder p;
           p.path( "/lib:/usr/lib" );
           p.extensions( ".a:.so" );
           std::cout << p.find( "libz" ) << std::endl;
           

That would print an empty string if it finds nothing, or a string if it finds any of the following:

Maintainer's note:

This cide was one of my very first STL-based classes, and the implementation probably shows that very clearly. That said, it has worked well for me for some four years now without any appeciable maintenance. :)

Definition at line 47 of file path_finder.hpp.


Member Typedef Documentation

typedef std::list<std::string> s11n::plugin::path_finder::string_list

A list type returned by some functions.

Definition at line 54 of file path_finder.hpp.


Constructor & Destructor Documentation

s11n::plugin::path_finder::path_finder ( const std::string &  path = std::string(),
const std::string &  ext = std::string(),
const std::string &  pathsep = ":" 
)

Creates object with the given path/extension list.

virtual s11n::plugin::path_finder::~path_finder (  )  [virtual]


Member Function Documentation

std::string s11n::plugin::path_finder::path_string (  )  const

Returns a ":"-separated string of all paths added via add/path().

void s11n::plugin::path_finder::path_separator ( const std::string &  sep  ) 

Sets the string used as a separator for the string-based variants of path(), extentions(), etc.

const std::string& s11n::plugin::path_finder::path_separator (  )  const

Returns the path separator string.

Default is ":";

virtual std::size_t s11n::plugin::path_finder::path ( const std::string &  p  )  [virtual]

Sets the path to p, which should be a path_separator()-delimited string.

Returns the number of path elements parsed from p.

Referenced by s11n::plugin::path_finder_s11n::operator()().

virtual std::size_t s11n::plugin::path_finder::path ( const string_list p  )  [virtual]

Sets the path to the given list of directories.

Returns the number of elements in the list.

virtual void s11n::plugin::path_finder::add_path ( const std::string &  p  )  [virtual]

Adds p to the path.

May be path_separtor()-delimited.

virtual void s11n::plugin::path_finder::add_extension ( const std::string &  ext = std::string()  )  [virtual]

Adds a "search extension." Sample: finder.extension( ".txt:.TXT" ); Will now try all path combinations with the rightmost characters matching ".txt" or ".TXT" (in that order).

Be sure to include a period if you want that searched - that is so this class can be used to find non-files and those with non-traditional extensions, like "foo_EXT".

virtual std::size_t s11n::plugin::path_finder::extensions ( const std::string &  ext  )  [virtual]

like add_extension(), but overwrites extension list.

Returns the number of entries parsed from the string.

Referenced by s11n::plugin::path_finder_s11n::operator()().

virtual std::size_t s11n::plugin::path_finder::extensions ( const string_list p  )  [virtual]

Sets the extensions list to the given list.

Returns the number of entries in p.

std::string s11n::plugin::path_finder::extensions_string (  )  const

Returns the path_separator()-delimited listed of file suffixes to use when searching for a path.

const string_list& s11n::plugin::path_finder::extensions (  )  const

Returns this object's extensions list.

string_list& s11n::plugin::path_finder::extensions (  ) 

Non-const overload, intended for serialization.

static std::string s11n::plugin::path_finder::join_list ( const string_list list,
const std::string &  separator 
) [static]

Helper function to collapse a list into a string.

This function was changed from a normal member to static member in s11n version 1.1.3.

static bool s11n::plugin::path_finder::is_accessible ( const std::string &  path  )  [static]

Returns true if path is readable.

static std::string s11n::plugin::path_finder::basename ( const std::string &   )  [static]

Returns the "base name" of the given string: any part following the final directory separator character.

static std::string s11n::plugin::path_finder::dir_separator (  )  [static]

Returns a platform-dependent path separator.

This is set when the class is compiled.

std::string s11n::plugin::path_finder::find ( const std::string &  resourcename,
bool  check_cache = true 
) const

Returns the full path of the given resource, provided it could be found using the available lookup paths/extensions and is readable.

Note that this might return a relative path, especially if the resourcename passed to it immediately resolves to an existing resource. It returns an empty string if the resourcename cannot be found in the filesystem tree (or is otherwise unaccessible).

If check_cache is false then this function ignores its lookup cache and searches again, otherwise it uses a cache. When caching it will always return the same result for any given resourcename.

void s11n::plugin::path_finder::clear_cache (  ) 

Empties the hit-cache used by find().

const string_list& s11n::plugin::path_finder::path (  )  const

Returns a list of all items added via add_path() and path().

string_list& s11n::plugin::path_finder::path (  ) 

Non-const overload, intended for serialization.

bool s11n::plugin::path_finder::empty (  )  const

Returns true if this object has no paths or extensions.


The documentation for this class was generated from the following file:
Generated on Sun Apr 27 11:46:50 2008 for libs11n-1.2.6 by  doxygen 1.5.3