FilePaths Class Reference

#include <FilePaths.hpp>

Inheritance diagram for FilePaths:

Public Member Functions
	FilePaths (SimulationItem *parent)
string	input (string name) const
string	inputPath () const
string	output (string name) const
string	outputPath () const
string	outputPrefix () const
void	setInputPath (string value)
void	setOutputPath (string value)
void	setOutputPrefix (string value)
Public Member Functions inherited from SimulationItem
template<class T >
T *	find (bool setup=true) const
template<class T >
T *	interface (int levels=-999999, bool setup=true) const
virtual string	itemName () const
void	setup ()
string	typeAndName () const
Public Member Functions inherited from Item
	Item (const Item &)=delete
virtual	~Item ()
void	addChild (Item *child)
const vector< Item * > &	children () const
virtual void	clearItemListProperty (const PropertyDef *property)
void	destroyChild (Item *child)
virtual bool	getBoolProperty (const PropertyDef *property) const
virtual vector< double >	getDoubleListProperty (const PropertyDef *property) const
virtual double	getDoubleProperty (const PropertyDef *property) const
virtual string	getEnumProperty (const PropertyDef *property) const
virtual int	getIntProperty (const PropertyDef *property) const
virtual vector< Item * >	getItemListProperty (const PropertyDef *property) const
virtual Item *	getItemProperty (const PropertyDef *property) const
virtual string	getStringProperty (const PropertyDef *property) const
int	getUtilityProperty (string name) const
virtual void	insertIntoItemListProperty (const PropertyDef *property, int index, Item *item)
Item &	operator= (const Item &)=delete
Item *	parent () const
virtual void	removeFromItemListProperty (const PropertyDef *property, int index)
virtual void	setBoolProperty (const PropertyDef *property, bool value)
virtual void	setDoubleListProperty (const PropertyDef *property, vector< double > value)
virtual void	setDoubleProperty (const PropertyDef *property, double value)
virtual void	setEnumProperty (const PropertyDef *property, string value)
virtual void	setIntProperty (const PropertyDef *property, int value)
virtual void	setItemProperty (const PropertyDef *property, Item *item)
virtual void	setStringProperty (const PropertyDef *property, string value)
void	setUtilityProperty (string name, int value)
virtual string	type () const

Static Public Member Functions
static vector< string >	expectedPacks ()
static int	expectedPackVersion (string name)
static int	installedPackVersion (string name)
static string	resource (string name)
static string	resourceName (string type, const vector< string > &segments)

Protected Member Functions
void	setupSelfBefore () override
Protected Member Functions inherited from SimulationItem
	SimulationItem ()
virtual bool	offersInterface (const std::type_info &interfaceTypeInfo) const
virtual void	setupSelfAfter ()
virtual void	setupSelfBefore ()
Protected Member Functions inherited from Item
	Item ()

Private Attributes
string	_inputPath
string	_outputPath
string	_outputPrefix

Detailed Description

The FilePaths class manages the paths for the input and output files of a simulation, and for the resources included with the code or provided externally.

Input and output files

A client program determines the input and output file paths and the prefix for output file names, presumably from the command line options. It then stores this information in the FilePaths instance held by the simulation, so that the simulation hierarchy can easily access it.

Resource files

The FilePaths class also offers static functions for locating the resource files used by the simulation hierarchy. These files can be provided as part of the build tree in the source code repository, or can be installed in a directory next to (and thus outside of) the build tree. This mechanism allows to provide small and frequently-used resource files as part of the source code repository, while requiring larger resource files to be downloaded seperately.

Resource files are identified by their filename, without any directory or path information. In other words, a given resource file could be located in any of the supported directories (or nested subdirectory). On the other hand, this means there can be only a single resource with a particular name.

Specifically, when first invoked, the FilePaths class builds a list of all available resource files by iterating over the following directories and all nested subdirectories inside these directories, recursively:

• the resources directory inside the SKIRT build tree.
• the resources directory (if any) next to the SKIRT git directory (i.e. outside of the build tree).

The top-level directories are iterated in the order listed above. The iteration order for the nested subdirectories inside the top-level directories is unspecified. The first occurrence of a particular filename is stored; any subsequent occurrences of the same filename are ignored.

Resource packs

Finally, the FilePaths class offers static functions that support versioning for resource packs, which are usually installed in the resource directory outside of the build tree.

A resource pack is a set of resource files contained in a resource subdirectory, called the pack directory, that contains a file named version.txt. The first token in this text file's contents is interpreted as the integer version number of the resource pack. The name of the resource pack is determined by the segment of the pack directory name after the last underscore. The resource files in the pack can reside in nested subdirectories.

Furthermore, a resource file named ExpectedResources.txt can be provided as part of the build tree. This text file lists the names and version numbers of the resource packs expected to be installed, one pack name and corresponding version number per line.

The FilePaths class offers functions to retrieve information on the expected and installed resource packs from these files. This information can be used by the client program to verify that the appropriate resource pack versions have been installed.

Constructor & Destructor Documentation

FilePaths()

FilePaths::FilePaths ( SimulationItem *  parent )

explicit

This constructor creates a file path object that is hooked up as a child to the specified parent in the simulation hierarchy, so that it will automatically be deleted. The setup() function is not called by this constructor.

Member Function Documentation

expectedPacks()

static vector< string > FilePaths::expectedPacks ( )

static

This function returns a list of the names of all expected packs, in the order listed in the ExpectedResources.txt resource file, or the empty list if that resource file is missing or empty.

expectedPackVersion()

static int FilePaths::expectedPackVersion ( string  name )

static

This function returns the expected version number for the resource pack with the specified name, or zero if the name is not in the list of expected packs.

input()

string FilePaths::input

(

string

name

)

const

This function returns the absolute canonical path for an input file with the specified name, relative to the input path returned by inputPath().

inputPath()

string FilePaths::inputPath

(

)

const

Returns the (absolute or relative) path for input files.

installedPackVersion()

static int FilePaths::installedPackVersion ( string  name )

static

This function returns the version number for the installed resource pack with the specified name, or zero if the pack is not installed.

output()

string FilePaths::output

(

string

name

)

const

This function returns the absolute canonical path for an output file with the specified name, relative to the output path returned by outputPath(). The prefix returned by outputPrefix() is inserted in front of the filename specified here. The prefix and the filename are separated by an underscore.

outputPath()

string FilePaths::outputPath

(

)

const

Returns the (absolute or relative) path for output files.

outputPrefix()

string FilePaths::outputPrefix

(

)

const

Returns the prefix for output file names.

resource()

static string FilePaths::resource ( string  name )

static

This function returns the absolute canonical path for a resource file with the specified filename. The filename should not include any directory segments (just the base filename and filename extension). The function searches the list of available resource files as described in the class header. If the specified resource file cannot be located, a fatal error is thrown.

resourceName()

static string FilePaths::resourceName ( string  type, const vector< string > &  segments  )

static

This function returns the filename (without directory segments) for a resource file with the specified type and with a filename including the specified segments. The function searches the list of available resource files as described in the class header.

For a resource file to be considered by this function, the end of its filename (including the filename extension) must match the specified type string, and the filename must also contain each of the specified segments. If no or multiple resources files match these requirements, the function throws a fatal error. If a single resource file matches, the function returns its filename.

setInputPath()

void FilePaths::setInputPath

(

string

value

)

Sets the (absolute or relative) path for input files. An empty string (the default value) means the current directory.

setOutputPath()

void FilePaths::setOutputPath

(

string

value

)

Sets the (absolute or relative) path for output files. An empty string (the default value) means the current directory.

setOutputPrefix()

void FilePaths::setOutputPrefix

(

string

value

)

Sets the prefix for output file names; the default is empty (i.e. no prefix).

setupSelfBefore()

void FilePaths::setupSelfBefore ( )

overrideprotectedvirtual

This function determines and caches the resource file paths that can be returned by this class. This avoids repeated searches through the resource directories, and allows reporting any problems as early as possible in the program's lifecycle.

Reimplemented from SimulationItem.

---

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

• FilePaths.hpp