PathSearch Class Reference
[Input]

List of all members.

Classes

class  ExcFileNotFound
class  ExcNoClass

Public Types

enum  Position { back, front, after_none }

Public Member Functions

 PathSearch (const std::string &cls, const unsigned int debug=0)
std::string find (const std::string &filename, const char *open_mode="r")
std::string find (const std::string &filename, const std::string &suffix, const char *open_mode="r")
template<class STREAM >
void show (STREAM &stream) const
void add_path (const std::string &path, Position pos=back)
void add_suffix (const std::string &suffix, Position pos=back)

Static Public Member Functions

static void add_class (const std::string &cls)

Private Types

typedef std::map< std::string,
std::vector< std::string >
>::value_type 
map_type

Static Private Member Functions

static void initialize_classes ()
static std::vector< std::string > & get_path_list (const std::string &cls)
static std::vector< std::string > & get_suffix_list (const std::string &cls)

Private Attributes

const std::string cls
std::vector< std::string > & my_path_list
std::vector< std::string > & my_suffix_list
const unsigned int debug

Static Private Attributes

static std::map< std::string,
std::vector< std::string > > 
path_lists
static std::map< std::string,
std::vector< std::string > > 
suffix_lists
static std::string empty


Detailed Description

Support for searching files in a list of paths and with a list of suffixes.

A list of search paths is maintained for each file class supported. A file class is defined by a unique string. The classes provided are

MESH
mesh input files in various formats (see GridIn)
PARAMETER
Parameter files (.prm)

Additional file classes can be added easily by using add_class().

Usage: First, you construct a PathSearch object for a certain file class, e.g. meshes. Then, you use the find() method to obtain a full path name and you can open the file.

 #include <base/path_search.h>

 DEAL_II_NAMESPACE_OPEN
 PathSearch search("MESH");
 std::string full_name = search.find("grid");
 std::ifstream in(full_name.c_str());
 ...

This piece of code will first traverse all paths in the list set up for file class MESH. If it manages to open a file, it returns the istream object. If not, it will try to append the first suffix of the suffix list and do the same. And so on. If no file is found in the end, an exception is thrown.

If you want to restrict your search to a certain mesh format, .inp for instance, then either use "grid.inp" in the code above or use the alternative find(const std::string&,const std::string&,const char*) function

 std::string full_name = search.find("grid", ".inp");

Path lists are by default starting with the current directory ("./"), followed optionally by a standard directory of deal.II. Use show() to find out the path list for a given class. Paths and suffixes can be added using the functions add_path() and add_suffix(), respectively.

Note:
Directories in the path list should always end with a trailing "/", while suffixes should always start with a dot. These characters are not added automatically (allowing you to do some real file name editing).
Todo:
Add support for environment variables like in kpathsea.
Author:
Guido Kanschat, Luca Heltai 2005

Member Typedef Documentation

typedef std::map<std::string, std::vector<std::string> >::value_type PathSearch::map_type [private]

Type of values in the class maps.


Member Enumeration Documentation

Position for adding a new item to a list.

Enumerator:
back  Add new item at end of list.
front  Add new item at front of list.
after_none  Add in path list after empty element.


Constructor & Destructor Documentation

PathSearch::PathSearch ( const std::string &  cls,
const unsigned int  debug = 0 
)

Constructor. The first argument is a string identifying the class of files to be searched for.

The debug argument determines the verbosity of this class.


Member Function Documentation

std::string PathSearch::find ( const std::string &  filename,
const char *  open_mode = "r" 
)

Find a file in the class specified by the constructor and return its complete path name (including a possible suffix).

File search works by actually trying to open the file. If fopen is successful with the provided open_mode, then the file is found, otherwise the search continues.

Warning:
Be careful with open_mode! In particular, use "w" with great care! If the file does not exist, it cannot be found. If it does exist, the fopen function will truncate it to zero length.
Parameters:
filename The base name of the file to be found, without path components and suffix.
open_mode The mode handed over to the fopen function.

std::string PathSearch::find ( const std::string &  filename,
const std::string &  suffix,
const char *  open_mode = "r" 
)

Find a file in the class specified by the constructor and return its complete path name. Do not use the standard suffix list, but only try to apply the suffix given.

File search works by actually trying to open the file. If fopen is successful with the provided open_mode, then the file is found, otherwise the search continues.

Warning:
Be careful with open_mode! In particular, use "w" with great care! If the file does not exist, it cannot be found. If it does exist, the fopen function will truncate it to zero length.
Parameters:
filename The base name of the file to be found, without path components and suffix.
suffix The suffix to be used for opening.
open_mode The mode handed over to the fopen function.

template<class STREAM >
void PathSearch::show ( STREAM &  stream  )  const [inline]

Show the paths and suffixes used for this object.

References cls, my_path_list, and my_suffix_list.

static void PathSearch::add_class ( const std::string &  cls  )  [static]

Add a new class.

void PathSearch::add_path ( const std::string &  path,
Position  pos = back 
)

Add a path to the current class. See PathSearch::Position for possible position arguments.

void PathSearch::add_suffix ( const std::string &  suffix,
Position  pos = back 
)

Add a path to the current class. See PathSearch::Position for possible position arguments.

static void PathSearch::initialize_classes (  )  [static, private]

Initialize the static list objects for further use.

static std::vector<std::string>& PathSearch::get_path_list ( const std::string &  cls  )  [static, private]

Get path list for a certain class. Used to set up my_path_list in constructor.

static std::vector<std::string>& PathSearch::get_suffix_list ( const std::string &  cls  )  [static, private]

Get suffix list for a certain class. Used to set up my_suffix_list in constructor.


Member Data Documentation

const std::string PathSearch::cls [private]

The file class handled by this object.

Referenced by show().

std::map<std::string, std::vector<std::string> > PathSearch::path_lists [static, private]

All path lists for all classes, such that we can build them only once.

std::map<std::string, std::vector<std::string> > PathSearch::suffix_lists [static, private]

List of suffixes for each class.

std::vector<std::string>& PathSearch::my_path_list [private]

Path list for the class this object belongs to.

Referenced by show().

std::vector<std::string>& PathSearch::my_suffix_list [private]

Suffix list for the class this object belongs to.

Referenced by show().

const unsigned int PathSearch::debug [private]

Debug flag. No output if zero.

std::string PathSearch::empty [static, private]

The empty string.


The documentation for this class was generated from the following file:

deal.II documentation generated on Sat Aug 15 16:52:11 2009 by doxygen 1.5.9