#include <deal.II/base/path_search.h>

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 StreamType >
void	show (StreamType &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)

static ::ExceptionBase &	ExcNoClass (std::string arg1)

static ::ExceptionBase &	ExcFileNotFound (std::string arg1, std::string arg2)

Private Types
using	map_type = std::map< std::string, std::vector< std::string > >::value_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 <deal.II/base/path_search.h>
 
::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

Definition at line 84 of file path_search.h.

Member Typedef Documentation

◆ map_type

using PathSearch::map_type = std::map<std::string, std::vector<std::string> >::value_type

private

Type of values in the class maps.

Definition at line 200 of file path_search.h.

Member Enumeration Documentation

◆ Position

enum PathSearch::Position

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.

Definition at line 90 of file path_search.h.

Constructor & Destructor Documentation

◆ PathSearch()

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.

Definition at line 103 of file path_search.cc.

Member Function Documentation

◆ find() [1/2]

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.

Definition at line 171 of file path_search.cc.

◆ find() [2/2]

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.

Definition at line 112 of file path_search.cc.

◆ show()

template<class StreamType >

void PathSearch::show ( StreamType & stream ) const

inline

Show the paths and suffixes used for this object.

Definition at line 264 of file path_search.h.

◆ add_class()

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

static

Add a new class.

Definition at line 198 of file path_search.cc.

◆ add_path()

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.

Definition at line 214 of file path_search.cc.

◆ add_suffix()

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.

Definition at line 232 of file path_search.cc.

◆ initialize_classes()

void PathSearch::initialize_classes ( )

staticprivate

Initialize the static list objects for further use.

Definition at line 33 of file path_search.cc.

◆ get_path_list()

std::vector< std::string > & PathSearch::get_path_list ( const std::string & cls )

staticprivate

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

Definition at line 70 of file path_search.cc.

◆ get_suffix_list()

std::vector< std::string > & PathSearch::get_suffix_list ( const std::string & cls )

staticprivate

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

Definition at line 87 of file path_search.cc.

Member Data Documentation

◆ cls

const std::string PathSearch::cls

private

The file class handled by this object.

Definition at line 225 of file path_search.h.

◆ path_lists

std::map< std::string, std::vector< std::string > > PathSearch::path_lists

staticprivate

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

Definition at line 230 of file path_search.h.

◆ suffix_lists

std::map< std::string, std::vector< std::string > > PathSearch::suffix_lists

staticprivate

List of suffixes for each class.

Definition at line 235 of file path_search.h.

◆ my_path_list

std::vector<std::string>& PathSearch::my_path_list

private

Path list for the class this object belongs to.

Definition at line 240 of file path_search.h.

◆ my_suffix_list

std::vector<std::string>& PathSearch::my_suffix_list

private

Suffix list for the class this object belongs to.

Definition at line 245 of file path_search.h.

◆ debug

const unsigned int PathSearch::debug

private

Debug flag. No output if zero.

Definition at line 250 of file path_search.h.

◆ empty

std::string PathSearch::empty

staticprivate

The empty string.

Definition at line 255 of file path_search.h.

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

include/deal.II/base/path_search.h
source/base/path_search.cc

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

◆ map_type

Member Enumeration Documentation

◆ Position

Constructor & Destructor Documentation

◆ PathSearch()

Member Function Documentation

◆ find() [1/2]

◆ find() [2/2]

◆ show()

◆ add_class()

◆ add_path()

◆ add_suffix()

◆ initialize_classes()

◆ get_path_list()

◆ get_suffix_list()

Member Data Documentation

◆ cls

◆ path_lists

◆ suffix_lists

◆ my_path_list

◆ my_suffix_list

◆ debug

◆ empty