Basic file handling operations. More...

#include <OpenMS/SYSTEM/File.h>

Classes
struct	OpenMSDataPath_
	Bundles the resolved OpenMS data path with a human-readable description of where it was found (for diagnostics). More...

Public Types
enum class	CopyOptions { OVERWRITE , SKIP , CANCEL }
	Copy directory recursively. More...

enum class	MatchingFileListsStatus { MATCH = 0 , ORDER_MISMATCH = 1 , SET_MISMATCH = 2 }

Static Public Member Functions
static std::string	getExecutablePath ()

static bool	exists (const std::string &file)
	Method used to test if a `file` exists.

static bool	empty (const std::string &file)
	Return true if the file does not exist or the file is empty.

static bool	executable (const std::string &file)
	Method used to test if a `file` is executable.

static UInt64	fileSize (const std::string &file)
	The filesize in bytes (or -1 on error, e.g. if the file does not exist)

static Int64	getModificationTime (const std::string &file)
	Last modification time of `file`, in seconds since the Unix epoch (or -1 on error).

static bool	rename (const std::string &from, const std::string &to, bool overwrite_existing=true, bool verbose=true)
	Rename a file.

static bool	copyDirRecursively (const std::string &from_dir, const std::string &to_dir, File::CopyOptions option=CopyOptions::OVERWRITE)

static bool	copy (const std::string &from, const std::string &to)
	Copy a file (if it exists). Returns true if successful.

static bool	remove (const std::string &file)
	Removes a file (if it exists).

static bool	removeDirRecursively (const std::string &dir_name)
	Removes a directory and all its contents recursively (absolute path). Returns true if successful.

static bool	removeDir (const std::string &dir_name)
	Removes a directory and all its contents (absolute path). Returns true if successful.

static bool	makeDir (const std::string &dir_name)

static std::string	absolutePath (const std::string &file)
	Replaces the relative path in the argument with the absolute path.

static std::string	toFileURI (const std::string &file)
	Convert a local path to an absolute file URI.

static std::string	basename (const std::string &file)

static std::string	stemName (const std::string &file)

static std::string	extension (const std::string &file)

static StringList	listDirectories (const std::string &dir)

static std::string	path (const std::string &file)

static bool	readable (const std::string &file)
	Return true if the file exists and is readable.

static bool	writable (const std::string &file)
	Return true if the file is writable.

static bool	isDirectory (const std::string &path)
	Return true if the given path specifies a directory.

static std::string	find (const std::string &filename, StringList directories=StringList())
	Looks up the location of the file `filename`.

static bool	fileList (const std::string &dir, const std::string &file_pattern, StringList &output, bool full_path=false)
	Retrieves a list of files matching `file_pattern` in directory `dir` (returns filenames without paths unless `full_path` is true)

static std::string	findDoc (const std::string &filename)
	Resolves a partial file name to a documentation file in the doc-folder.

static std::string	getUniqueName (bool include_hostname=true)
	Returns a string, consisting of date, time, hostname, process id, and a incrementing number. This can be used for temporary files.

static std::string	getOpenMSDataPath ()

static const std::string &	getOpenMSDataPathSource ()
	Returns a human-readable description of where getOpenMSDataPath() resolved from.

static StringList	getPathLocations ()
	Extract list of directories from a concatenated string (usually $PATH).

static StringList	getPathLocations (const std::string &path)
	Extract list of directories from an explicit concatenated path string.

static bool	findExecutable (std::string &exe_filename)
	Searches for an executable with the given name (similar to where (Windows) or which (Linux/MacOS)

static std::string	findSiblingTOPPExecutable (const std::string &toolName)
	Searches for an executable with the given name.

static MatchingFileListsStatus	validateMatchingFileNames (const StringList &sl1, const StringList &sl2, bool basename=true, bool ignore_extension=true)
	Helper function to test if filenames provided in two StringLists match.

Static Private Member Functions
static bool	isOpenMSDataPath_ (const std::string &path)
	Check if the given path is a valid OPENMS_DATA_PATH.

static const OpenMSDataPath_ &	resolveOpenMSDataPath_ ()
	Resolve (once, thread-safe) and return the OpenMS data path together with where it was found.

Detailed Description

Basic file handling operations.

Class Documentation

◆ OpenMS::File::OpenMSDataPath_

struct OpenMS::File::OpenMSDataPath_

Bundles the resolved OpenMS data path with a human-readable description of where it was found (for diagnostics).

Class Members
string	path	the resolved shared-data directory
string	source	human-readable origin, e.g. "the OPENMS_DATA_PATH environment variable"

Member Enumeration Documentation

◆ CopyOptions

enum class CopyOptions

strong

Copy directory recursively.

Copies a source directory to a new target directory (recursive). If the target directory already exists, files will be added. If files from the source already exist in the target, option allows for the following behaviour:

OVERWRITE: Overwrite the file in the target directory if it already exists. SKIP: Skip the file in the target directory if it already exists. CANCEL: Cancel the copy process if file already exists in target directory - return false.

Parameters

[in]	from_dir	Source directory
[in]	to_dir	Target directory
[in]	option	Specify the copy option (OVERWRITE, SKIP, CANCEL)

Returns: True on success

Enumerator
OVERWRITE
SKIP
CANCEL

◆ MatchingFileListsStatus

enum class MatchingFileListsStatus

strong

Enumerator
MATCH
ORDER_MISMATCH
SET_MISMATCH

Member Function Documentation

◆ absolutePath()

static std::string absolutePath ( const std::string & file )

static

Replaces the relative path in the argument with the absolute path.

Referenced by TOPPViewBase::addDataFile().

◆ basename()

static std::string basename ( const std::string & file )

static

Returns the basename of the file (without the path). No checking is done on the filesystem, i.e. '/path/some_entity' will return 'some_entity', irrespective of 'some_entity' is a file or a directory. However, '/path/some_entity/' will return ''.

Referenced by TOPPViewBase::addDataFile(), TOPPASBase::addTOPPASFile(), MQMsms::exportFeatureMap(), MQEvidence::exportFeatureMap(), NucleicAcidSearchEngine::main_(), TOPPASBase::refreshParameters(), MS1LabeledRatioQuantifier::run(), TOPPASBase::saveCurrentPipelineAs(), TOPPASBase::savePipeline(), TOPPASBase::savePipelineAs(), INIFileEditorWindow::updateWindowTitle(), and DIAQCMetrics::writeMzQC().

◆ copy()

static bool copy	(	const std::string &	from,
		const std::string &	to
	)

static

Copy a file (if it exists). Returns true if successful.

◆ copyDirRecursively()

static bool copyDirRecursively	(	const std::string &	from_dir,
		const std::string &	to_dir,
		File::CopyOptions	option = `CopyOptions::OVERWRITE`
	)

static

◆ empty()

static bool empty ( const std::string & file )

static

Return true if the file does not exist or the file is empty.

◆ executable()

static bool executable ( const std::string & file )

static

Method used to test if a file is executable.

◆ exists()

static bool exists ( const std::string & file )

static

Method used to test if a file exists.

Referenced by TOPPViewBase::addDataFile(), OpenMS::NuXLPresets::getAllPresetsNames(), OpenMS::NuXLPresets::getPresets(), TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), and OpenMS::Internal::ClassTest::validateTmpFiles().

◆ extension()

static std::string extension ( const std::string & file )

static

Returns the file extension including the leading dot. Recognizes compound OpenMS extensions like ".mzML.gz". E.g., "/path/sample.mzML.gz" returns ".mzML.gz", "/path/file.txt" returns ".txt". Returns empty string if there is no extension: "/path/file" returns "".

◆ fileList()

static bool fileList	(	const std::string &	dir,
		const std::string &	file_pattern,
		StringList &	output,
		bool	full_path = `false`
	)

static

Retrieves a list of files matching file_pattern in directory dir (returns filenames without paths unless full_path is true)

Returns: true => there are matching files

◆ fileSize()

static UInt64 fileSize ( const std::string & file )

static

The filesize in bytes (or -1 on error, e.g. if the file does not exist)

◆ find()

static std::string find	(	const std::string &	filename,
		StringList	directories = `StringList()`
	)

static

Looks up the location of the file filename.

The following locations are checked in this order:

the directories in directories
the directory contained in the environment variable $OPENMS_DATA_PATH
the 'share/OpenMS/' directory of the OpenMS install directory

Exceptions

FileNotFound is thrown, if the file is not found

Referenced by QApplicationTOPP::QApplicationTOPP(), and DIAQCMetrics::writeMzQC().

◆ findDoc()

static std::string findDoc ( const std::string & filename )

static

Resolves a partial file name to a documentation file in the doc-folder.

Using find() to locate the documentation file under OPENMS_DATA_PATH, OPENMS_SOURCE_PATH, OPENMS_BINARY_PATH + "/../../doc" (or a variation for MacOS packages)

Will return the filename with the full path to the local documentation. If this call fails, try the web documentation (http://www.openms.de/current_doxygen/) instead.

Parameters

[in] filename The doc file name to find.

Returns: The full path to the requested file.

Exceptions

FileNotFound is thrown, if the file is not found

◆ findExecutable()

static bool findExecutable ( std::string & exe_filename )

static

Searches for an executable with the given name (similar to where (Windows) or which (Linux/MacOS)

This function can be used to find the full path+filename to an executable in the PATH environment. Only the first hit (by order in PATH) is returned. If the exe_filename has a relative or full path which points to an existing file, PATH information will not be used. The function returns true if the filename was found (exists) and false otherwise. Note: this does not require the file to have executable permission set (this is not tested) The returned content of exe_filename is only valid if true is returned.

Parameters

[in,out] exe_filename The executable to search for.

Returns: true if exe_filename could be resolved to a full path and it exists

◆ findSiblingTOPPExecutable()

static std::string findSiblingTOPPExecutable ( const std::string & toolName )

static

Searches for an executable with the given name.

Parameters

[in] toolName The executable to search for.

Exceptions

FileNotFound is thrown, if the tool executable was not found.

Referenced by TOPPViewBase::runTOPPTool_().

◆ getExecutablePath()

static std::string getExecutablePath ( )

static

Retrieve path of current executable (useful to find other TOPP tools) The returned path is either just an EMPTY string if the call to system subroutines failed or the complete path including a trailing "/", to enable usage of this function as File::getExecutablePath() + "mytool"

◆ getModificationTime()

static Int64 getModificationTime ( const std::string & file )

static

Last modification time of file, in seconds since the Unix epoch (or -1 on error).

Reported against the Unix epoch rather than as a std::filesystem::file_time_type, whose clock epoch is implementation-defined: two standard libraries report different numbers for the same file. That distinction only matters once the value leaves the process – written to a file, or compared against one another machine recorded – which is exactly what a caller doing change detection tends to do with it.

◆ getOpenMSDataPath()

static std::string getOpenMSDataPath ( )

static

Returns the OpenMS data path (resolved from the compiled-in path and executable location; the OPENMS_DATA_PATH environment variable is only used as a last-resort fallback)

Referenced by OpenMS::NuXLPresets::getAllPresetsNames(), OpenMS::NuXLPresets::getPresets(), and TOPPASBase::openExampleDialog().

◆ getOpenMSDataPathSource()

static const std::string & getOpenMSDataPathSource ( )

static

Returns a human-readable description of where getOpenMSDataPath() resolved from.

(e.g. "exe-relative (../share/OpenMS)"). Useful for diagnostics.

◆ getPathLocations() [1/2]

static StringList getPathLocations ( )

static

Extract list of directories from a concatenated string (usually $PATH).

Depending on platform, the components are split based on ":" (Linux/Mac) or ";" (Windows). All paths use the '/' as separator and end in '/'. E.g. for 'PATH=/usr/bin:/home/unicorn' the result is {"/usr/bin/", "/home/unicorn/"} or 'PATH=c:\temp;c:\Windows' the result is {"c:/temp/", "c:/Windows/"}

Uses the value of the $PATH environment variable (or an empty string if $PATH is unset).

◆ getPathLocations() [2/2]

static StringList getPathLocations ( const std::string & path )

static

Extract list of directories from an explicit concatenated path string.

Depending on platform, the components are split based on ":" (Linux/Mac) or ";" (Windows). All paths use the '/' as separator and end in '/'. Note: the path string is passed as input to enable proper testing (env vars are usually read-only).

◆ getUniqueName()

static std::string getUniqueName ( bool include_hostname = true )

static

Returns a string, consisting of date, time, hostname, process id, and a incrementing number. This can be used for temporary files.

Parameters

[in] include_hostname add hostname into result - potentially a long string

Returns: a unique name

Referenced by TOPPViewBase::showTOPPDialog_(), and TOPPASBase::TOPPASBase().

◆ isDirectory()

static bool isDirectory ( const std::string & path )

static

Return true if the given path specifies a directory.

◆ isOpenMSDataPath_()

static bool isOpenMSDataPath_ ( const std::string & path )

staticprivate

Check if the given path is a valid OPENMS_DATA_PATH.

◆ listDirectories()

static StringList listDirectories ( const std::string & dir )

static

Returns a sorted list of subdirectory absolute paths (non-recursive) in the given directory. Uses '/' separators. Returns an empty list on any error or if the path is not a directory (no throw).

◆ makeDir()

static bool makeDir ( const std::string & dir_name )

static

Creates a directory (absolute path or relative to the current working dir), even if subdirectories do not exist. Returns true if successful. If the path already exists when this function is called, it will return true.

◆ path()

static std::string path ( const std::string & file )

static

Returns the path of the file (without the file name and without path separator). If just a filename is given without any path, then "." is returned. No checking is done on the filesystem, i.e. '/path/some_entity' will return '/path', irrespective of 'some_entity' is a file or a directory. However, '/path/some_entity/' will return '/path/some_entity'.

Referenced by TOPPViewBase::updateCurrentPath(), and INIFileEditorWindow::updateWindowTitle().

◆ readable()

static bool readable ( const std::string & file )

static

Return true if the file exists and is readable.

Referenced by TOPPViewBase::finishTOPPToolExecution(), and INIFileEditorWindow::openFile().

◆ remove()

static bool remove ( const std::string & file )

static

Removes a file (if it exists).

Returns: Returns true if the file was successfully deleted (or if it did not exist).

Referenced by TOPPViewBase::finishTOPPToolExecution(), and TOPPViewBase::runTOPPTool_().

◆ removeDir()

static bool removeDir ( const std::string & dir_name )

static

Removes a directory and all its contents (absolute path). Returns true if successful.

◆ removeDirRecursively()

static bool removeDirRecursively ( const std::string & dir_name )

static

Removes a directory and all its contents recursively (absolute path). Returns true if successful.

Referenced by TOPPASBase::~TOPPASBase().

◆ rename()

static bool rename	(	const std::string &	from,
		const std::string &	to,
		bool	overwrite_existing = `true`,
		bool	verbose = `true`
	)

static

Rename a file.

If from and to point to the same file (symlinks are resolved), no action will be taken and true is returned. If the target already exists (and is not identical to the source), this function will fail unless overwrite_existing is true.

Parameters

[in]	from	Source filename
[in]	to	Target filename
[in]	overwrite_existing	Delete already existing target, before renaming
[in]	verbose	Print message to OPENMS_LOG_ERROR if something goes wrong.

Returns: True on success

◆ resolveOpenMSDataPath_()

static const OpenMSDataPath_ & resolveOpenMSDataPath_ ( )

staticprivate

Resolve (once, thread-safe) and return the OpenMS data path together with where it was found.

◆ stemName()

static std::string stemName ( const std::string & file )

static

Returns the basename of the file without any known file extension. Delegates to FileHandler::stripExtension(File::basename(file)). E.g., "/path/sample.mzML.gz" returns "sample", "/path/data.featureXML" returns "data". Unknown extensions are stripped at the last dot: "/path/file.txt" returns "file". Directories with dots in the path are handled correctly: "/my.dir/file" returns "file".

Referenced by TOPPViewBase::addDataFile().

◆ toFileURI()

static std::string toFileURI ( const std::string & file )

static

Convert a local path to an absolute file URI.

The returned URI uses forward slashes on every platform and the standard three-slash form for local absolute paths (e.g. file:///C:/data/run.mzML on Windows).

Parameters

[in] file Local file or directory path

Returns: Absolute file URI

◆ validateMatchingFileNames()

static MatchingFileListsStatus validateMatchingFileNames	(	const StringList &	sl1,
		const StringList &	sl2,
		bool	basename = `true`,
		bool	ignore_extension = `true`
	)

static

Helper function to test if filenames provided in two StringLists match.

Passing several InputFilesLists is error-prone as users may provide files in a different order. This helper function performs validation and returns one of three states:

MATCH (0): Files match perfectly (considering basename/extension settings)
ORDER_MISMATCH (1): Same set of files but in different order
SET_MISMATCH (2): Different sets of files (including different counts)

Parameters

[in]	sl1	First StringList with filenames
[in]	sl2	Second StringList with filenames
[in]	basename	If set to true, only basenames are compared
[in]	ignore_extension	If set to true, extensions are ignored (e.g., useful to compare spectra filenames to ID filenames)

Returns: MatchingFileListsStatus indicating the validation result

◆ writable()

static bool writable ( const std::string & file )

static

Return true if the file is writable.

Referenced by MQExporterHelper::isValid(), TOPPViewBase::runTOPPTool_(), and TOPPViewBase::showTOPPDialog_().

Classes

Public Types

Static Public Member Functions

Static Private Member Functions

Detailed Description

Class Documentation

◆ OpenMS::File::OpenMSDataPath_

Member Enumeration Documentation

◆ CopyOptions

◆ MatchingFileListsStatus

Member Function Documentation

◆ absolutePath()

◆ basename()

◆ copy()

◆ copyDirRecursively()

◆ empty()

◆ executable()

◆ exists()

◆ extension()

◆ fileList()

◆ fileSize()

◆ find()

◆ findDoc()

◆ findExecutable()

◆ findSiblingTOPPExecutable()

◆ getExecutablePath()

◆ getModificationTime()

◆ getOpenMSDataPath()

◆ getOpenMSDataPathSource()

◆ getPathLocations() [1/2]

◆ getPathLocations() [2/2]

◆ getUniqueName()

◆ isDirectory()

◆ isOpenMSDataPath_()

◆ listDirectories()

◆ makeDir()

◆ path()

◆ readable()

◆ remove()

◆ removeDir()

◆ removeDirRecursively()

◆ rename()

◆ resolveOpenMSDataPath_()

◆ stemName()

◆ toFileURI()

◆ validateMatchingFileNames()

◆ writable()