| OpenMS 2.5.0

Classes | Public Types | Static Public Member Functions | Static Private Member Functions | Static Private Attributes | Friends | List of all members
File Class Reference
System

Basic file handling operations. More...

`#include <OpenMS/SYSTEM/File.h>`

## Classes

class | TemporaryFiles_
| Internal helper class, which holds temporary filenames and deletes these files at program exit. More...

## Public Types

enum | CopyOptions { OVERWRITE, SKIP, CANCEL }
| Copy directory recursively. More...

## Static Public Member Functions

static String | getExecutablePath ()
static bool | exists (const String &file)
| Method used to test if a `file` exists. More...
static bool | empty (const String &file)
| Return true if the file does not exist or the file is empty. More...
static bool | rename (const String &from, const String &to, bool overwrite_existing=true, bool verbose=true)
| Rename a file. More...
static bool | copyDirRecursively (const QString &from_dir, const QString &to_dir, File::CopyOptions option=CopyOptions::OVERWRITE)
static bool | remove (const String &file)
| Removes a file (if it exists). More...
static bool | removeDirRecursively (const String &dir_name)
| Removes the subdirectories of the specified directory (absolute path). Returns true if successful. More...
static bool | removeDir (const QString &dir_name)
| Removes the directory and all subdirectories (absolute path). More...
static String | absolutePath (const String &file)
| Replaces the relative path in the argument with the absolute path. More...
static String | basename (const String &file)
| Returns the basename of the file (without the path). More...
static String | path (const String &file)
| Returns the path of the file (without the file name). More...
static String | removeExtension (const String &file)
static bool | readable (const String &file)
| Return true if the file exists and is readable. More...
static bool | writable (const String &file)
| Return true if the file is writable. More...
static bool | isDirectory (const String &path)
| Return true if the given path specifies a directory. More...
static String | find (const String &filename, StringList directories=StringList())
| Looks up the location of the file `filename`. More...
static bool | fileList (const String &dir, const 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) More...
static String | findDoc (const String &filename)
| Resolves a partial file name to a documentation file in the doc-folder. More...
static 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. More...
static String | getOpenMSDataPath ()
| Returns the OpenMS data path (environment variable overwrites the default installation path) More...
static String | getOpenMSHomePath ()
| Returns the OpenMS home path (environment variable overwrites the default home path) More...
static String | getTempDirectory ()
| The current OpenMS temporary data path (for temporary files) More...
static String | getUserDirectory ()
static Param | getSystemParameters ()
static String | findDatabase (const String &db_name)
static StringList | getPathLocations (const String &path=std::getenv("PATH"))
| Extract list of directories from a concatenated string (usually $PATH). More...
static bool | findExecutable (OpenMS::String &exe_filename)
| Searches for an executable with the given name (similar to where (Windows) or which (Linux/MacOS) More...
static String | findSiblingTOPPExecutable (const String &toolName)
| Searches for an executable with the given name. More...
static const String & | getTemporaryFile (const String &alternative_file="")
| Obtain a temporary filename, ensuring automatic deletion upon exit. More...

## Static Private Member Functions

static Param | getSystemParameterDefaults_ ()
| get defaults for the system's Temp-path, user home directory etc. More...
static bool | isOpenMSDataPath_ (const String &path)
| Check if the given path is a valid OPENMS_DATA_PATH. More...

## Static Private Attributes

static TemporaryFiles_ | temporary_files_
| private list of temporary filenames, which are deleted upon program exit More...

## Friends

class | TOPPBase

## Detailed Description

Basic file handling operations.

## Member Enumeration Documentation

## ◆ CopyOptions

enum 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

  from_dir | Source directory
  to_dir | Target directory
  option | Specify the copy option (OVERWRITE, SKIP, CANCEL)

Returns
  True on success

Enumerator
OVERWRITE |
SKIP |
CANCEL |

## Member Function Documentation

## ◆ absolutePath()

static String absolutePath | ( | const String & | file | ) |

static

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

Referenced by TOPPViewBase::addDataFile(), TOPPViewBase::addRecentFile_(), UTILProteomicsLFQ::main_(), UTILProteomicsLFQ::mapMzML2Ids_(), and UTILProteomicsLFQ::quantifyFraction_().

## ◆ basename()

static String basename | ( | const String & | file | ) |

static

Returns the basename of the file (without the path).

Referenced by TOPPViewBase::addDataFile(), TOPPASBase::addTOPPASFile(), DTAFile::load(), UTILProteomicsLFQ::recalibrateMasses_(), TOPPASBase::refreshParameters(), NucleicAcidSearchEngine::registerIDMetaData_(), AccurateMassSearchEngine::resolveAutoMode_(), TOPPASBase::saveCurrentPipelineAs(), TOPPASBase::savePipeline(), TOPPASBase::savePipelineAs(), and INIFileEditorWindow::updateWindowTitle().

## ◆ copyDirRecursively()

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

static

## ◆ empty()

static bool empty | ( | const String & | file | ) |

static

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

## ◆ exists()

static bool exists | ( | const String & | file | ) |

static

Method used to test if a `file` exists.

Referenced by TOPPViewBase::addDataFile(), MS2File::load(), MascotInfile::load(), MascotGenericFile::load(), TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), UTILProteomicsLFQ::main_(), and UTILProteomicsLFQ::mapMzML2Ids_().

## ◆ fileList()

static bool fileList | ( | const String & | dir,
|  | const 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

## ◆ find()

static String find | ( | const 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 DigestionEnzymeDB< DigestionEnzymeRNA, RNaseDB >::readEnzymesFromFile_().

## ◆ findDatabase()

static String findDatabase | ( | const String & | db_name | ) |

static

uses File::find() to search for a file names `db_name` in the 'id_db_dir' param of the OpenMS system parameters

Exceptions

  FileNotFound | is thrown, if the file is not found

## ◆ findDoc()

static String findDoc | ( | const 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 String with the full path to the local documentation. If this call fails, try the web documentation (http://www.openms.de/current_doxygen/) instead.

Parameters

  String | 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 | ( | OpenMS::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 String findSiblingTOPPExecutable | ( | const String & | toolName | ) |

static

Searches for an executable with the given name.

Parameters

  toolName | The executable to search for.

Exceptions

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

Referenced by TOPPViewBase::runTOPPTool_().

## ◆ getExecutablePath()

static 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"

## ◆ getOpenMSDataPath()

static String getOpenMSDataPath | ( |  | ) |

static

Returns the OpenMS data path (environment variable overwrites the default installation path)

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

## ◆ getOpenMSHomePath()

static String getOpenMSHomePath | ( |  | ) |

static

Returns the OpenMS home path (environment variable overwrites the default home path)

## ◆ getPathLocations()

static StringList getPathLocations | ( | const String & | path = `std::getenv("PATH")` | ) |

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:;c:' the result is {"c:/temp/", "c:/Windows/"}

Note: the environment variable is passed as input to enable proper testing (env vars are usually read-only).

## ◆ getSystemParameterDefaults_()

static Param getSystemParameterDefaults_ | ( |  | ) |

static private

get defaults for the system's Temp-path, user home directory etc.

## ◆ getSystemParameters()

static Param getSystemParameters | ( |  | ) |

static

get the system's default OpenMS.ini file in the users home directory (<home>/OpenMS/OpenMS.ini) or create/repair it if required order: 1. <OPENMS_HOME_DIR>/OpenMS/OpenMS.ini if environmental variable set 2. user home directory <home>/OpenMS/OpenMS.ini

## ◆ getTempDirectory()

static String getTempDirectory | ( |  | ) |

static

The current OpenMS temporary data path (for temporary files)

Referenced by TOPPASBase::TOPPASBase(), and TOPPASBase::~TOPPASBase().

## ◆ getTemporaryFile()

static const String& getTemporaryFile | ( | const String & | alternative_file = `""` | ) |

static

Obtain a temporary filename, ensuring automatic deletion upon exit.

The file is not actually created and only deleted at exit if it exists.

However, if 'alternative_file' is given and not empty, no temporary filename is created and 'alternative_file' is returned (and not destroyed upon exit). This is useful if you have an optional output file, which may, or may not be requested, but you need its content regardless, e.g. for intermediate plotting with R. Thus you can just call this function to get a file which can be used and gets automatically destroyed if needed.

Parameters

  alternative_file | If this string is not empty, no action is taken and it is used as return value

Returns
  Full path to a temporary file

## ◆ getUniqueName()

static 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

  include_hostname | add hostname into result - potentially a long string

Returns
  a unique name

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

## ◆ getUserDirectory()

static String getUserDirectory | ( |  | ) |

static

The current OpenMS user data path (for result files) Tries to set the user directory in following order: 1. OPENMS_HOME_DIR if environmental variable set 2. "home_dir" entry in OpenMS.ini 3. user home directory

## ◆ isDirectory()

static bool isDirectory | ( | const String & | path | ) |

static

Return true if the given path specifies a directory.

## ◆ isOpenMSDataPath_()

static bool isOpenMSDataPath_ | ( | const String & | path | ) |

static private

Check if the given path is a valid OPENMS_DATA_PATH.

## ◆ path()

static String path | ( | const String & | file | ) |

static

Returns the path of the file (without the file name).

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

## ◆ readable()

static bool readable | ( | const String & | file | ) |

static

Return true if the file exists and is readable.

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

## ◆ remove()

static bool remove | ( | const 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::rerunTOPPTool().

## ◆ removeDir()

static bool removeDir | ( | const QString & | dir_name | ) |

static

Removes the directory and all subdirectories (absolute path).

## ◆ removeDirRecursively()

static bool removeDirRecursively | ( | const String & | dir_name | ) |

static

Removes the subdirectories of the specified directory (absolute path). Returns true if successful.

Referenced by TOPPASBase::~TOPPASBase().

## ◆ removeExtension()

static String removeExtension | ( | const String & | file | ) |

static

Returns the file name without the extension

The extension is the suffix of the string up to and including the last dot.

If no extension is found, the whole file name is returned

Referenced by TOPPViewBase::addDataFile().

## ◆ rename()

static bool rename | ( | const String & | from,
|  | const 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

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

Returns
  True on success

## ◆ writable()

static bool writable | ( | const String & | file | ) |

static

Return true if the file is writable.

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

## Friends And Related Function Documentation

## ◆ TOPPBase

friend class TOPPBase

friend

## Member Data Documentation

## ◆ temporary_files_

TemporaryFiles_ temporary_files_

static private

private list of temporary filenames, which are deleted upon program exit