This class finds data files given an instrument name (optionally) and a run number. More...

#include <FileFinder.h>

Classes
struct	FileInfo
	Per-hint state threaded through the file-search pipeline. More...

Public Member Functions
std::string	extractAllowedSuffix (std::string &userString) const
	Run numbers can be followed by an allowed string.

const API::Result< std::filesystem::path >	findRun (const std::string &hintstr, const std::vector< std::string > &exts={}, const bool useExtsOnly=false) const
	Find a path to a single file from a hint.

std::vector< std::filesystem::path >	findRuns (const std::string &hintstr, const std::vector< std::string > &exts={}, const bool useExtsOnly=false) const
	Find a list of files from a comma- and range-separated hint string.

std::vector< std::filesystem::path >	findRuns (const std::vector< std::string > &hints, const std::vector< std::string > &exts={}, const bool useExtsOnly=false) const

bool	getCaseSensitive () const
	Option to get if file finder should be case sensitive.

std::string	getExtension (const std::string &filename, const std::vector< std::string > &exts) const
	DO NOT USE! MADE PUBLIC FOR TESTING ONLY.

std::filesystem::path	getFullPath (const std::string &filename, const bool ignoreDirs=false) const
	Return the full path to the file given its name.

const Kernel::InstrumentInfo	getInstrument (const std::string &hintstr, const bool returnDefaultIfNotFound=true, const std::string &defaultInstrument="") const
	DO NOT USE! MADE PUBLIC FOR TESTING ONLY.

void	getUniqueExtensions (const std::vector< std::string > &extensionsToAdd, std::vector< std::string > &uniqueExts) const
	Given a set of already determined extensions and new extensions, create a set of all extensions.

std::string	makeFileName (const std::string &hintstr, const Kernel::InstrumentInfo &instrument) const
	DO NOT USE! MADE PUBLIC FOR TESTING ONLY.

void	setCaseSensitive (const bool cs)
	Option to set if file finder should be case sensitive.

std::pair< std::string, std::string >	toInstrumentAndNumber (const std::string &hintstr, const Kernel::InstrumentInfo &instrument) const
	Extracts the instrument name and run number from a hint.

std::pair< std::string, std::string >	toInstrumentAndNumber (const std::string &hintstr, const std::string &defaultInstrument="") const
	Extracts the instrument name and run number from a hint.

std::filesystem::path	tryResolvePathWithExtension (const std::string &filename) const
	If the hint already carries an extension, return its resolved full path in the data search dirs (or empty if not found).

Static Public Member Functions
static std::vector< IArchiveSearch_sptr >	getArchiveSearch (const Kernel::FacilityInfo &facility)

Private Member Functions
	FileFinderImpl ()
	Default constructor.

	FileFinderImpl (const FileFinderImpl &)
	Copy constructor.

const API::Result< std::filesystem::path >	getArchivePath (const std::vector< IArchiveSearch_sptr > &archs, const std::set< std::string > &hintstrs, const std::vector< std::string > &exts) const
	Return the path to the file found in archive.

const API::Result< std::filesystem::path >	getISISInstrumentDataCachePath (const std::filesystem::path &cacheDir, const std::set< std::string > &hintstrs, const std::vector< std::string > &exts) const

bool	isMalformedRange (const std::string &token) const
	Decide whether a token the parser could not expand is a malformed run range rather than a literal file hint.

FileFinderImpl &	operator= (const FileFinderImpl &)
	Assignment operator.

void	performArchiveSearch (std::vector< FileInfo > &fileInfos) const

void	performBatchedArchiveSearch (std::vector< FileInfo > &fileInfos, const IArchiveSearch_sptr &sharedArch) const

void	performCacheSearch (std::vector< FileInfo > &fileInfos) const

void	performFileSearch (std::vector< FileInfo > &fileInfos) const

void	performPerFileArchiveSearch (std::vector< FileInfo > &fileInfos) const

void	prepareFileInfo (FileInfo &fileInfo, const std::vector< std::string > &extensionsProvided, bool useOnlyExtensionsProvided) const

void	processFileInfos (std::vector< FileInfo > &fileInfos, const std::vector< std::string > &extensionsProvided, bool useOnlyExtensionsProvided) const

std::string	validateRuns (const std::string &searchText) const
	A method that returns error messages if the provided runs are invalid.

Static Private Member Functions
static IArchiveSearch_sptr	batchableArchive (const std::vector< FileInfo > &fileInfos)
	If every unfound FileInfo shares a single archive (and instrument) that supports batched multi-hint lookups, return that archive.

Private Attributes
int	m_globOption
	glob option - set to case sensitive or insensitive

Static Private Attributes
static const std::string	ALLOWED_SUFFIX = "-add"
	a string that is allowed at the end of any run number

Friends
class	::FileFinderISISInstrumentDataCacheTest

struct	Mantid::Kernel::CreateUsingNew< FileFinderImpl >

Detailed Description

This class finds data files given an instrument name (optionally) and a run number.

Author: Roman Tolchenov, Tessella plc

Date: 23/07/2010

Definition at line 41 of file FileFinder.h.

Constructor & Destructor Documentation

◆ FileFinderImpl() [1/2]

Mantid::API::FileFinderImpl::FileFinderImpl ( )

private

Default constructor.

Definition at line 113 of file FileFinder.cpp.

References Mantid::Kernel::Glob::GLOB_DEFAULT, m_globOption, and setCaseSensitive().

◆ FileFinderImpl() [2/2]

Mantid::API::FileFinderImpl::FileFinderImpl ( const FileFinderImpl & )

private

Copy constructor.

Member Function Documentation

◆ batchableArchive()

IArchiveSearch_sptr Mantid::API::FileFinderImpl::batchableArchive ( const std::vector< FileInfo > & fileInfos )

staticprivate

If every unfound FileInfo shares a single archive (and instrument) that supports batched multi-hint lookups, return that archive.

If every unfound FileInfo has the same single archive and instrument, and that archive supports batched multi-hint lookups, return it.

Otherwise nullptr — caller falls back to per-file archive lookups.

Otherwise return nullptr. Two unfound entries with equal InstrumentInfo always have the same archive list because getArchiveSearch() is deterministic per facility, so we only need to compare instruments rather than archive types.

Definition at line 774 of file FileFinder.cpp.

Referenced by performArchiveSearch().

◆ extractAllowedSuffix()

std::string Mantid::API::FileFinderImpl::extractAllowedSuffix ( std::string & userString ) const

Run numbers can be followed by an allowed string.

Check if there is one, remove it from the name and return the string, else return empty

Parameters

userString run number that may have a suffix

Returns: the suffix, if there was one

Definition at line 162 of file FileFinder.cpp.

References ALLOWED_SUFFIX.

Referenced by makeFileName().

◆ findRun()

const API::Result< std::filesystem::path > Mantid::API::FileFinderImpl::findRun	(	const std::string &	hintstr,
		const std::vector< std::string > &	extensionsProvided = `{}`,
		const bool	useOnlyExtensionsProvided = `false`
	)		const

Find a path to a single file from a hint.

Parameters

hintstr	:: hint string to look for filename.
extensionsProvided	:: Vector of aditional file extensions to consider. Optional. If not provided, facility extensions used.
useOnlyExtensionsProvided	:: Optional bool. If it's true (and extensionsProvided is not empty), search for the file using extensionsProvided only. If it's false, use extensionsProvided AND facility extensions.

Returns: The full path to the file if found, or an empty string otherwise.

Definition at line 412 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), error, Mantid::API::g_log, getInstrument(), Mantid::API::FileFinderImpl::FileInfo::hint, processFileInfos(), Mantid::Kernel::Strings::strip(), tryResolvePathWithExtension(), and validateRuns().

◆ findRuns() [1/2]

std::vector< std::filesystem::path > Mantid::API::FileFinderImpl::findRuns	(	const std::string &	hintstr,
		const std::vector< std::string > &	extensionsProvided = `{}`,
		const bool	useOnlyExtensionsProvided = `false`
	)		const

Find a list of files from a comma- and range-separated hint string.

The hint is split on comma operators, then each token is expanded by the multi-file-name parser (which understands ranges like "123-135" or "123:135:2", instrument prefixes, and zero padding). The resulting flat list of file hints is resolved via findRuns(vector).

Parameters

hintstr	:: Comma-separated hint string. Only the first token of a range may carry an instrument name.
extensionsProvided	:: Optional file extensions. If empty the facility extensions are used.
useOnlyExtensionsProvided	:: If true, search using only extensionsProvided; otherwise combine with facility extensions.

Returns: One full path per resolved file, in input order.

Exceptions

std::invalid_argument	if the input fails ASCII validation, if a token expands into a range too large for the parser to load, or if a token looks like a malformed run range (see isMalformedRange). Tokens the parser does not understand but that look like literal files are passed through as literal hints and surface as Exception::NotFoundError if they don't exist on disk.
Exception::NotFoundError	if any (literal or expanded) file cannot be found.

Definition at line 523 of file FileFinder.cpp.

References error, findRuns(), isMalformedRange(), Mantid::Kernel::MultiFileNameParsing::Parser::setTrimWhiteSpaces(), Mantid::Kernel::Strings::strip(), and validateRuns().

Referenced by findRuns(), MantidQt::API::FindFilesWorker::run(), and runFinderProxy().

◆ findRuns() [2/2]

std::vector< std::filesystem::path > Mantid::API::FileFinderImpl::findRuns	(	const std::vector< std::string > &	hints,
		const std::vector< std::string > &	exts = `{}`,
		const bool	useExtsOnly = `false`
	)		const

Definition at line 639 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), error, Mantid::API::g_log, getInstrument(), Mantid::API::FileFinderImpl::FileInfo::hint, processFileInfos(), tryResolvePathWithExtension(), validateRuns(), and Mantid::Kernel::Logger::warning().

◆ getArchivePath()

const API::Result< std::filesystem::path > Mantid::API::FileFinderImpl::getArchivePath	(	const std::vector< IArchiveSearch_sptr > &	archs,
		const std::set< std::string > &	hintstrs,
		const std::vector< std::string > &	exts
	)		const

private

Return the path to the file found in archive.

Parameters

archs	:: A list of archives to search
hintstrs	:: A list of hints (without extensions) to pass to the archive
exts	:: A list of extensions to check for in turn against each file

Returns: The full path if the file exists and can be found in one of the search locations or an empty string otherwise.

Definition at line 968 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), and Mantid::API::g_log.

Referenced by performPerFileArchiveSearch().

◆ getArchiveSearch()

std::vector< IArchiveSearch_sptr > Mantid::API::FileFinderImpl::getArchiveSearch ( const Kernel::FacilityInfo & facility )

static

Definition at line 385 of file FileFinder.cpp.

References Mantid::Kernel::FacilityInfo::archiveSearch(), Mantid::Kernel::Logger::debug(), Mantid::API::g_log, name, and Mantid::Kernel::FacilityInfo::name().

Referenced by prepareFileInfo().

◆ getCaseSensitive()

bool Mantid::API::FileFinderImpl::getCaseSensitive ( ) const

Option to get if file finder should be case sensitive.

Returns: cs :: If case sensitive return true, if not case sensitive return false

Definition at line 141 of file FileFinder.cpp.

References Mantid::Kernel::Glob::GLOB_DEFAULT, and m_globOption.

Referenced by export_FileFinder(), getUniqueExtensions(), and prepareFileInfo().

◆ getExtension()

std::string Mantid::API::FileFinderImpl::getExtension	(	const std::string &	filename,
		const std::vector< std::string > &	exts
	)		const

DO NOT USE! MADE PUBLIC FOR TESTING ONLY.

Determine the extension from a filename.

Parameters

filename	The filename to get the extension from.
exts	The list of extensions to try before giving up and using the default: whatever happens after the '.'.

Returns: The extension. If one isn't determined it is an empty string.

Definition at line 342 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), and Mantid::API::g_log.

◆ getFullPath()

std::filesystem::path Mantid::API::FileFinderImpl::getFullPath	(	const std::string &	filename,
		const bool	ignoreDirs = `false`
	)		const

Return the full path to the file given its name.

Parameters

filename	:: A file name (without path) including extension
ignoreDirs	:: If true, directories that match are skipped unless the path given is already absolute

Returns: The full path if the file exists and can be found in one of the search locations or an empty string otherwise.

Definition at line 153 of file FileFinder.cpp.

References m_globOption.

Referenced by getFullPathProxy(), performFileSearch(), MantidQt::API::FindFilesWorker::run(), and tryResolvePathWithExtension().

◆ getInstrument()

const Kernel::InstrumentInfo Mantid::API::FileFinderImpl::getInstrument	(	const std::string &	hintstr,
		const bool	returnDefaultIfNotFound = `true`,
		const std::string &	defaultInstrument = `""`
	)		const

DO NOT USE! MADE PUBLIC FOR TESTING ONLY.

Return the InstrumentInfo as determined from the hint.

Parameters

hintstr	:: The name hint.
returnDefaultIfNotFound	:: Flag to control return. May throw exception if set to false.
defaultInstrument	:: The default instrument to return if not found. If empty, the system default is used.

Returns: The InstrumentInfo object.

Definition at line 187 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::API::g_log, and Mantid::Kernel::Exception::NotFoundError::what().

Referenced by findRun(), findRuns(), makeFileName(), and toInstrumentAndNumber().

◆ getISISInstrumentDataCachePath()

const API::Result< std::filesystem::path > Mantid::API::FileFinderImpl::getISISInstrumentDataCachePath	(	const std::filesystem::path &	cacheDir,
		const std::set< std::string > &	hintstrs,
		const std::vector< std::string > &	exts
	)		const

private

Definition at line 917 of file FileFinder.cpp.

Referenced by performCacheSearch().

◆ getUniqueExtensions()

void Mantid::API::FileFinderImpl::getUniqueExtensions	(	const std::vector< std::string > &	extensionsToAdd,
		std::vector< std::string > &	uniqueExts
	)		const

Given a set of already determined extensions and new extensions, create a set of all extensions.

If not in an extension-is-case-sensitive environment, only add the lower case OR upper case version of the extension

Parameters

extensionsToAdd	:: a vector of extensions to add
uniqueExts	:: a vector of currently included extensions

Definition at line 449 of file FileFinder.cpp.

References getCaseSensitive().

Referenced by prepareFileInfo().

◆ isMalformedRange()

bool Mantid::API::FileFinderImpl::isMalformedRange ( const std::string & token ) const

private

Decide whether a token the parser could not expand is a malformed run range rather than a literal file hint.

Decide whether a token the multi-file parser could not expand is a malformed run range rather than a genuine literal file hint.

This mirrors the historical "fileSuspected" heuristic: a token containing a path separator or the "-add" suffix, or one carrying a file extension, is treated as a literal file and passed through unchanged. Any other token that looks like a run range (i.e. splitting on '-' yields two or more parts, e.g. "MUSR15189-n15193" or "1-2-3") but that the parser could not expand is reported as malformed, restoring the old "Malformed range of runs" diagnostic so the user can rule out a genuine file-not-found. Note this is only consulted after the parser has already rejected the token, so well-formed ranges (which the parser expands successfully) never reach here.

Parameters

token :: A single, already comma-split hint token.

Returns: true if the token should be reported as a malformed run range.

Definition at line 488 of file FileFinder.cpp.

References ALLOWED_SUFFIX, Mantid::Kernel::StringTokenizer::count(), Mantid::Kernel::StringTokenizer::TOK_IGNORE_EMPTY, and Mantid::Kernel::StringTokenizer::TOK_TRIM.

Referenced by findRuns().

◆ makeFileName()

std::string Mantid::API::FileFinderImpl::makeFileName	(	const std::string &	hintstr,
		const Kernel::InstrumentInfo &	instrument
	)		const

DO NOT USE! MADE PUBLIC FOR TESTING ONLY.

Make a data file name (without extension) from a hint.

The hint can be either a run number or a run number prefixed with an instrument name/short name. If the instrument name is absent the default one is used.

Parameters

hintstr	:: The name hint
instrument	:: The current instrument object

Returns: The file name

Exceptions

NotFoundError	if a required default is not set
std::invalid_argument	if the argument is malformed or run number is too long

Definition at line 294 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::Kernel::InstrumentInfo::delimiter(), extractAllowedSuffix(), Mantid::API::g_log, getInstrument(), name, Mantid::Kernel::InstrumentInfo::name(), Mantid::Kernel::InstrumentInfo::shortName(), and toInstrumentAndNumber().

Referenced by prepareFileInfo().

◆ operator=()

FileFinderImpl & Mantid::API::FileFinderImpl::operator= ( const FileFinderImpl & )

private

Assignment operator.

◆ performArchiveSearch()

void Mantid::API::FileFinderImpl::performArchiveSearch ( std::vector< FileInfo > & fileInfos ) const

private

Definition at line 792 of file FileFinder.cpp.

References batchableArchive(), performBatchedArchiveSearch(), and performPerFileArchiveSearch().

Referenced by processFileInfos().

◆ performBatchedArchiveSearch()

void Mantid::API::FileFinderImpl::performBatchedArchiveSearch	(	std::vector< FileInfo > &	fileInfos,
		const IArchiveSearch_sptr &	sharedArch
	)		const

private

Definition at line 812 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::Kernel::Logger::error(), Mantid::API::g_log, and index.

Referenced by performArchiveSearch().

◆ performCacheSearch()

void Mantid::API::FileFinderImpl::performCacheSearch ( std::vector< FileInfo > & fileInfos ) const

private

Definition at line 743 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::API::g_log, and getISISInstrumentDataCachePath().

Referenced by processFileInfos().

◆ performFileSearch()

void Mantid::API::FileFinderImpl::performFileSearch ( std::vector< FileInfo > & fileInfos ) const

private

Definition at line 685 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::API::g_log, and getFullPath().

Referenced by processFileInfos().

◆ performPerFileArchiveSearch()

void Mantid::API::FileFinderImpl::performPerFileArchiveSearch ( std::vector< FileInfo > & fileInfos ) const

private

Definition at line 857 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::Kernel::Logger::error(), Mantid::API::g_log, and getArchivePath().

Referenced by performArchiveSearch().

◆ prepareFileInfo()

void Mantid::API::FileFinderImpl::prepareFileInfo	(	FileInfo &	fileInfo,
		const std::vector< std::string > &	extensionsProvided,
		bool	useOnlyExtensionsProvided
	)		const

private

◆ processFileInfos()

void Mantid::API::FileFinderImpl::processFileInfos	(	std::vector< FileInfo > &	fileInfos,
		const std::vector< std::string > &	extensionsProvided,
		bool	useOnlyExtensionsProvided
	)		const

private

Definition at line 628 of file FileFinder.cpp.

References performArchiveSearch(), performCacheSearch(), performFileSearch(), and prepareFileInfo().

Referenced by findRun(), and findRuns().

◆ setCaseSensitive()

void Mantid::API::FileFinderImpl::setCaseSensitive ( const bool cs )

Option to set if file finder should be case sensitive.

Parameters

cs	:: If true then set to case sensitive

Definition at line 129 of file FileFinder.cpp.

References Mantid::Kernel::Glob::GLOB_CASELESS, Mantid::Kernel::Glob::GLOB_DEFAULT, and m_globOption.

Referenced by export_FileFinder(), and FileFinderImpl().

◆ toInstrumentAndNumber() [1/2]

std::pair< std::string, std::string > Mantid::API::FileFinderImpl::toInstrumentAndNumber	(	const std::string &	hintstr,
		const Kernel::InstrumentInfo &	instr
	)		const

Extracts the instrument name and run number from a hint.

Parameters

hintstr	:: The name hint
instr	:: The instrument for the file

Returns: A pair of instrument name and run number

Definition at line 231 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::Kernel::InstrumentInfo::filePrefix(), Mantid::API::g_log, Mantid::Kernel::InstrumentInfo::name(), Mantid::Kernel::InstrumentInfo::shortName(), and Mantid::Kernel::InstrumentInfo::zeroPadding().

◆ toInstrumentAndNumber() [2/2]

std::pair< std::string, std::string > Mantid::API::FileFinderImpl::toInstrumentAndNumber	(	const std::string &	hintstr,
		const std::string &	defaultInstrument = `""`
	)		const

Extracts the instrument name and run number from a hint.

Parameters

hintstr	:: The name hint
defaultInstrument	:: The default instrument to use if the hint does not contain an instrument name. If empty, the system default is used.

Returns: A pair of instrument name and run number

Definition at line 219 of file FileFinder.cpp.

References getInstrument(), and toInstrumentAndNumber().

Referenced by makeFileName(), and toInstrumentAndNumber().

◆ tryResolvePathWithExtension()

std::filesystem::path Mantid::API::FileFinderImpl::tryResolvePathWithExtension ( const std::string & filename ) const

If the hint already carries an extension, return its resolved full path in the data search dirs (or empty if not found).

Returns empty for hints without an extension (which are treated as run-number hints elsewhere).

Definition at line 994 of file FileFinder.cpp.

References Mantid::Kernel::Logger::debug(), Mantid::API::g_log, and getFullPath().

Referenced by findRun(), and findRuns().

◆ validateRuns()

std::string Mantid::API::FileFinderImpl::validateRuns ( const std::string & searchText ) const

private

A method that returns error messages if the provided runs are invalid.

Performs validation on the search text entered into the File Finder.

It will return an error message if a problem is found.

Parameters

searchText :: The text to validate.

Returns: An error message if something is invalid.

Definition at line 465 of file FileFinder.cpp.

Referenced by findRun(), findRuns(), and findRuns().

Friends And Related Symbol Documentation

◆ ::FileFinderISISInstrumentDataCacheTest

friend class ::FileFinderISISInstrumentDataCacheTest

friend

Definition at line 42 of file FileFinder.h.

◆ Mantid::Kernel::CreateUsingNew< FileFinderImpl >

friend struct Mantid::Kernel::CreateUsingNew< FileFinderImpl >

friend

Definition at line 72 of file FileFinder.h.

Member Data Documentation

◆ ALLOWED_SUFFIX

const std::string Mantid::API::FileFinderImpl::ALLOWED_SUFFIX = "-add"

staticprivate

a string that is allowed at the end of any run number

Definition at line 94 of file FileFinder.h.

Referenced by extractAllowedSuffix(), and isMalformedRange().

◆ m_globOption

int Mantid::API::FileFinderImpl::m_globOption

private

glob option - set to case sensitive or insensitive

Definition at line 125 of file FileFinder.h.

Referenced by FileFinderImpl(), getCaseSensitive(), getFullPath(), and setCaseSensitive().

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

Framework/API/inc/MantidAPI/FileFinder.h
Framework/API/src/FileFinder.cpp

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ FileFinderImpl() [1/2]

◆ FileFinderImpl() [2/2]

Member Function Documentation

◆ batchableArchive()

◆ extractAllowedSuffix()

◆ findRun()

◆ findRuns() [1/2]

◆ findRuns() [2/2]

◆ getArchivePath()

◆ getArchiveSearch()

◆ getCaseSensitive()

◆ getExtension()

◆ getFullPath()

◆ getInstrument()

◆ getISISInstrumentDataCachePath()

◆ getUniqueExtensions()

◆ isMalformedRange()

◆ makeFileName()

◆ operator=()

◆ performArchiveSearch()

◆ performBatchedArchiveSearch()

◆ performCacheSearch()

◆ performFileSearch()

◆ performPerFileArchiveSearch()

◆ prepareFileInfo()

◆ processFileInfos()

◆ setCaseSensitive()

◆ toInstrumentAndNumber() [1/2]

◆ toInstrumentAndNumber() [2/2]

◆ tryResolvePathWithExtension()

◆ validateRuns()

Friends And Related Symbol Documentation

◆ ::FileFinderISISInstrumentDataCacheTest

◆ Mantid::Kernel::CreateUsingNew< FileFinderImpl >

Member Data Documentation

◆ ALLOWED_SUFFIX

◆ m_globOption