[pclasses-cvs] pclasses2/include/pclasses/System PathFinder.h,NONE,1.1

[stephan b. <sg...@us...>]

Update of /cvsroot/pclasses/pclasses2/include/pclasses/System
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv23520/include/pclasses/System

Added Files:
	PathFinder.h 
Log Message:
egg

--- NEW FILE: PathFinder.h ---
#ifndef cl_PATHFINDER_H
#define cl_PATHFINDER_H
// Author: stephan beal <st...@s1...>
// License: Public Domain



#include <string>
#include <list>
#include <map>
#include <iostream>

// #include <cl/StringList.h>	// todo: get rid of this in the public interface.

namespace P { namespace System {
        /**
           PathFinder searches for keys using a set of prefixes
           (paths) and suffixes (file extensions).
           
           Example:

           <pre>
           PathFinder p;
           p.path( "/lib/lib:/usr/lib/lib" );
           p.extensions( ".a:.so" );
           cout << p.find( "z" );
           </pre>

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

           - z
           - /lib/libz
           - /lib/libz.a
           - /lib/libz.so
           - /usr/lib/libz
           - /usr/lib/libz.a
           - /usr/lib/libz.so

         */
	class PathFinder
	{
	      public:

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


		/**
                   Creates object with the given path/extension list.
                */
                PathFinder( const std::string & path = std::string(), const std::string & ext = std::string(), const std::string & pathsep = ":" );

                virtual ~PathFinder();
                
		/**
                   Returns a ":"-separated string of all paths added via add/path().
                */
		  std::string pathString() const;

                /**
                   Sets the string used as a separator for the
                   string-based variants of path(), extentions(), etc.
                */
		void pathSeparator( const std::string & sep );

                /**
                   Returns the path separator string. Default is ":";
                 */
		const std::string & pathSeparator() const;

		/**
                   Sets the path to p, which should be a path_separtor()-delimited string.
                   Returns the number of path elements parsed from p.
                */
		virtual size_t path( const std::string & p );

                /**
                   Sets the path to the given list of directories.
                   Returns the number of elements in the list.
                 */
		virtual size_t path( const string_list & p );

		/**
                   Adds p to the path. May be path_separtor()-delimited.
                */
		virtual void addPath( const std::string & p );

		/**
                   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 void addExtension( const std::string & ext = std::string() );
		/**
                   like addExtension(), but overwrites extension list.
                   Returns the number of entries parsed from the string.
                */
		virtual size_t extensions( const std::string & ext );
                /**
                   Sets the extensions list to the given list.
                   Returns the number of entries in p.
                 */
		virtual size_t extensions( const string_list & p );

		/**
                   Returns the pathSeparator()-delimited listed of file
                   suffixes to use when searching for a path.
                */
		  std::string extensionsString() const;
                /**
                   Returns this object's extensions list.
                 */
		const string_list & extensions() const;

                /**
                   Helper function to collapse a list into a string.
                 */
                std::string joinList( const string_list & list, const std::string & separator ) const;

                /**
                   Returns true if path is readable.
                 */
		static bool isAccessible( const std::string & path );

		/**
                   Returns the "base name" of the given string: any part
                   following the final directory separator character.
                */
		static std::string basename( const std::string & );

                /**
                   Returns a platform-dependent path separator. This
                   is set when the class is compiled.
                 */
		static std::string dirSeparator();

		/**
                   Returns the full path of the given resource, provided it could be found
                   in all paths or with all extensions added and provided it 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
                   it's lookup cache and searches again, otherwise it
                   uses a cache. When caching it will always return
                   the same result for any given resourcename.
                */
		std::string find( const std::string & resourcename, bool check_cache = true ) const;

                /**
                   Empties the hit-cache used by find().
                */
                void clearCache();

		/**
                   Returns a list of all items added via addPath() and path().
                */
		const string_list & path() const;


	      private:
		string_list paths;
		string_list exts;
		std::string pathseparator;
		typedef std::map < std::string, std::string > StringStringMap;
		typedef StringStringMap::iterator StringStringIterator;
		mutable StringStringMap hitcache;
	};


} } // namespaces
#endif // cl_PATHFINDER_H