SeqAn3  3.0.1
The Modern C++ library for sequence analysis.
seqan3::output_file_validator< file_t > Class Template Reference

A validator that checks if a given path is a valid output file. More...

#include <seqan3/argument_parser/validators.hpp>

+ Inheritance diagram for seqan3::output_file_validator< file_t >:

Public Types

using option_value_type = std::string
 Type of values that are tested by validator.
 

Public Member Functions

std::string get_help_page_message () const
 Returns a message that can be appended to the (positional) options help page info.
 
template<std::ranges::forward_range range_type>
void operator() (range_type const &v) const
 Tests whether every path in list v passes validation. See operator()(option_value_type const & value) for further information. More...
 
virtual void operator() (std::filesystem::path const &file) const override
 Tests whether path is does not already exists and is writable. More...
 
Constructors, destructor and assignment
 output_file_validator ()
 Default constructor. More...
 
 output_file_validator (output_file_validator const &)=default
 Defaulted.
 
 output_file_validator (output_file_validator &&)=default
 Defaulted.
 
output_file_validatoroperator= (output_file_validator const &)=default
 Defaulted.
 
output_file_validatoroperator= (output_file_validator &&)=default
 Defaulted.
 
virtual ~output_file_validator ()=default
 Virtual Destructor.
 
 output_file_validator (std::vector< std::string > extensions)
 Constructs from a given collection of valid extensions. More...
 
 file_validator_base ()=default
 Defaulted.
 
 file_validator_base (file_validator_base const &)=default
 Defaulted.
 
 file_validator_base (file_validator_base &&)=default
 Defaulted.
 

Protected Member Functions

void validate_filename (std::filesystem::path const &path) const
 Validates the given filename path based on the specified extensions. More...
 
void validate_readability (std::filesystem::path const &path) const
 Checks if the given path is readable. More...
 
void validate_writeability (std::filesystem::path const &path) const
 Checks if the given path is writable. More...
 

Protected Attributes

std::vector< std::stringextensions {}
 Stores the extensions.
 

Related Functions

(Note that these are not member functions.)

Requirements for seqan3::validator

You can expect these (meta-)functions on all types that implement seqan3::validator.

void operator() (option_value_type const &cmp) const
 Validates the value 'cmp' and throws a seqan3::validation_failed on failure. More...
 

Detailed Description

template<typename file_t = void>
class seqan3::output_file_validator< file_t >

A validator that checks if a given path is a valid output file.

Template Parameters
file_tThe type of the file to get the valid extensions for; void on default.

On construction, the validator can receive a list (std::vector over std::string) of valid file extensions. The struct acts as a functor that throws a seqan3::parser_invalid_argument exception whenever a given filename's extension (sts::string) is not in the given list of valid file extensions, if the file already exist, or if the parent path does not have the proper writer permissions.

int main(int argc, const char ** argv)
{
seqan3::argument_parser myparser{"Test", argc, argv}; // initialize
myparser.add_option(myfile,'f',"file","Output file containing the processed sequences.",
// an exception will be thrown if the user specifies a filename
// that does not have one of the extensions ["fa","fasta"],
// if the file already exists, or if the file is not writable.
try
{
myparser.parse();
}
catch (seqan3::parser_invalid_argument const & ext) // the user did something wrong
{
std::cerr << "[PARSER ERROR] " << ext.what() << "\n"; // customize your error message
return -1;
}
seqan3::debug_stream << "filename given by user passed validation: " << myfile << "\n";
return 0;
}

The valid extensions can also be obtained from a seqan3 formatted file type, e.g. seqan3::sequence_input_file, if it is given as template argument to this class. The following snippet demonstrates the different ways to instantiate the seqan3::output_file_validator.

int main(int argc, const char ** argv)
{
// Default constructed validator has an empty extension list.
seqan3::debug_stream << validator1.get_help_page_message() << "\n";
// Specify your own extensions for the output file.
seqan3::debug_stream << validator2.get_help_page_message() << "\n";
// Give the seqan3 file type as a template argument to get all valid extensions for this file.
seqan3::debug_stream << validator3.get_help_page_message() << "\n";
return 0;
}
Note
The validator works on every type that can be implicitly converted to std::filesystem::path.

Constructor & Destructor Documentation

◆ output_file_validator() [1/2]

template<typename file_t = void>
seqan3::output_file_validator< file_t >::output_file_validator ( )
inline

Default constructor.

If the class' template argument file_t names a valid seqan3 file type that contains a static member valid_formats, e.g. seqan3::sequence_input_file::valid_formats, then it generates the list of valid extensions from this file. Otherwise the extensions list is empty.

◆ output_file_validator() [2/2]

template<typename file_t = void>
seqan3::output_file_validator< file_t >::output_file_validator ( std::vector< std::string extensions)
inlineexplicit

Constructs from a given collection of valid extensions.

Parameters
[in]extensionsThe valid extensions to validate for.

This constructor is only available if file_t does not name a valid seqan3 file type that contains a static member valid_formats.

Member Function Documentation

◆ operator()() [1/2]

template<std::ranges::forward_range range_type>
void seqan3::file_validator_base::operator() ( range_type const &  v) const
inlineinherited

Tests whether every path in list v passes validation. See operator()(option_value_type const & value) for further information.

Template Parameters
range_typeThe type of range to check; must model std::ranges::forward_range and the value type must be convertible to std::filesystem::path.
Parameters
vThe input range to iterate over and check every element.
Exceptions
parser_invalid_argument

◆ operator()() [2/2]

template<typename file_t = void>
virtual void seqan3::output_file_validator< file_t >::operator() ( std::filesystem::path const &  file) const
inlineoverridevirtual

Tests whether path is does not already exists and is writable.

Parameters
fileThe input value to check.
Exceptions
parser_invalid_argumentif the validation process failed. Might be nested with std::filesystem::filesystem_error on unhandled OS API errors.

Implements seqan3::file_validator_base.

◆ validate_filename()

void seqan3::file_validator_base::validate_filename ( std::filesystem::path const &  path) const
inlineprotectedinherited

Validates the given filename path based on the specified extensions.

Parameters
pathThe filename path.
Exceptions
parser_invalid_argumentif the specified extensions don't match the given path, or std::filesystem::filesystem_error on underlying OS API errors.

◆ validate_readability()

void seqan3::file_validator_base::validate_readability ( std::filesystem::path const &  path) const
inlineprotectedinherited

Checks if the given path is readable.

Parameters
pathThe path to check.
Returns
true if readable, otherwise false.
Exceptions
seqan3::parser_invalid_argumentif the path is not readable, or std::filesystem::filesystem_error on underlying OS API errors.

◆ validate_writeability()

void seqan3::file_validator_base::validate_writeability ( std::filesystem::path const &  path) const
inlineprotectedinherited

Checks if the given path is writable.

Parameters
pathThe path to check.
Returns
true if writable, otherwise false.
Exceptions
seqan3::parser_invalid_argumentif the file could not be opened for writing, or std::filesystem::filesystem_error on underlying OS API errors.

Friends And Related Function Documentation

◆ operator()()

void operator() ( option_value_type const &  cmp) const
related

Validates the value 'cmp' and throws a seqan3::validation_failed on failure.

Template Parameters
option_value_typeThe type of the value to be validated.
Parameters
[in,out]cmpThe value to be validated.
Exceptions
seqan3::validation_failedif value 'cmp' does not pass validation.
Attention
This is a concept requirement, not an actual function (however types satisfying this concept will provide an implementation).

The documentation for this class was generated from the following file:
debug_stream.hpp
Provides seqan3::debug_stream and related types.
std::string
seqan3::argument_parser
The SeqAn command line parser.
Definition: argument_parser.hpp:153
std::vector
seqan3::DEFAULT
The default were no checking or special displaying is happening.
Definition: auxiliary.hpp:233
std::cerr
filesystem
This header includes C++17 filesystem support and imports it into namespace seqan3::filesystem (indep...
std::filesystem::path
validators.hpp
Provides some standard validators for (positional) options.
output.hpp
Provides seqan3::sequence_file_output and corresponding traits classes.
all.hpp
Meta-Header for the argument parser module.
seqan3::parser_invalid_argument
Argument parser exception that is thrown whenever there is an error while parsing the command line ar...
Definition: exceptions.hpp:37
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition: debug_stream.hpp:39
seqan3::output_file_validator
A validator that checks if a given path is a valid output file.
Definition: validators.hpp:585
std::invalid_argument::what
T what(T... args)