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 Types inherited from seqan3::file_validator_base
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.
virtual void	operator() (std::filesystem::path const &file) const override
	Tests whether path is does not already exists and is writable.
Constructors, destructor and assignment
	output_file_validator ()
	Default constructor.
	output_file_validator (output_file_validator const &)=default
	Defaulted.
	output_file_validator (output_file_validator &&)=default
	Defaulted.
output_file_validator &	operator= (output_file_validator const &)=default
	Defaulted.
output_file_validator &	operator= (output_file_validator &&)=default
	Defaulted.
virtual	~output_file_validator ()=default
	Virtual Destructor.
	output_file_validator (output_file_open_options const mode, std::vector< std::string > extensions=default_extensions())
	Constructs from a given overwrite mode and a list of valid extensions.
	file_validator_base ()=default
	Defaulted.
	file_validator_base (file_validator_base const &)=default
	Defaulted.
	file_validator_base (file_validator_base &&)=default
	Defaulted.
Public Member Functions inherited from seqan3::file_validator_base
template<std::ranges::forward_range range_type> requires (std::convertible_to<std::ranges::range_value_t<range_type>, std::filesystem::path const &> && !std::convertible_to<range_type, std::filesystem::path const &>)
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.
	file_validator_base ()=default
	Defaulted.
	file_validator_base (file_validator_base const &)=default
	Defaulted.
	file_validator_base (file_validator_base &&)=default
	Defaulted.
file_validator_base &	operator= (file_validator_base const &)=default
	Defaulted.
file_validator_base &	operator= (file_validator_base &&)=default
	Defaulted.
virtual	~file_validator_base ()=default

Static Public Member Functions
static std::vector< std::string >	default_extensions ()
	The default extensions of file_t.

Additional Inherited Members
Protected Member Functions inherited from seqan3::file_validator_base
bool	case_insensitive_string_ends_with (std::string_view str, std::string_view suffix) const
	Helper function that checks if a string is a suffix of another string. Case insensitive.
std::string	valid_extensions_help_page_message () const
	Returns the information of valid file extensions.
void	validate_filename (std::filesystem::path const &path) const
	Validates the given filename path based on the specified extensions.
void	validate_readability (std::filesystem::path const &path) const
	Checks if the given path is readable.
void	validate_writeability (std::filesystem::path const &path) const
	Checks if the given path is writable.
Protected Attributes inherited from seqan3::file_validator_base
std::vector< std::string >	extensions {}
	Stores the extensions.
Related Symbols inherited from validator
using	option_value_type
	The type of value on which the validator is called on.
void	operator() (option_value_type const &cmp) const
	Validates the value 'cmp' and throws a seqan3::validation_error on failure.

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_t

The 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 class acts as a functor that throws a seqan3::validation_error exception whenever a given filename's extension (std::string) is not in the given list of valid file extensions, or if the parent path does not have the proper writer permissions. In addition, the validator receives a seqan3::output_file_open_options which allows you to specify what to do if your output file already exists. seqan3::output_file_open_options::create_new will throw a seqan3::validation_error exception if it already exists and seqan3::output_file_open_options::open_or_create will skip this check (that means you are allowed to overwrite the existing file).

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <filesystem>
 
#include <seqan3/argument_parser/all.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main(int argc, char const ** argv)
{
    seqan3::argument_parser myparser{"Test", argc, argv}; // initialize
 
    std::filesystem::path myfile{};
 
    // Use the seqan3::output_file_open_options to indicate that you allow overwriting existing output files, ...
    myparser.add_option(
        myfile,
        'f',
        "file",
        "Output file containing the processed sequences.",
        seqan3::option_spec::standard,
        seqan3::output_file_validator{seqan3::output_file_open_options::open_or_create, {"fa", "fasta"}});
 
    // ... or that you will throw a seqan3::validation_error if the user specified output file already exists
    myparser.add_option(myfile,
                        'g',
                        "file2",
                        "Output file containing the processed sequences.",
                        seqan3::option_spec::standard,
                        seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"fa", "fasta"}});
 
    // 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::argument_parser_error 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.

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <seqan3/argument_parser/validators.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/sequence_file/output.hpp>
 
int main()
{
    // Default constructed validator has an empty extension list.
    seqan3::output_file_validator validator1{seqan3::output_file_open_options::create_new};
    seqan3::debug_stream << validator1.get_help_page_message() << '\n';
 
    // Specify your own extensions for the output file.
    seqan3::output_file_validator validator2{seqan3::output_file_open_options::create_new,
                                             std::vector{std::string{"exe"}, std::string{"fasta"}}};
    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::output_file_validator<seqan3::sequence_file_output<>> validator3{
        seqan3::output_file_open_options::create_new};
    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.

Remarks

For a complete overview, take a look at Argument Parser

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 ( output_file_open_options const  mode, std::vector< std::string >  extensions = default_extensions()  )

inlineexplicit

Constructs from a given overwrite mode and a list of valid extensions.

Parameters

[in]	mode	A seqan3::output_file_open_options indicating whether the validator throws if a file already exists.
[in]	extensions	The valid extensions to validate for. Defaults to seqan3::output_file_validator::default_extensions.

Member Function Documentation

default_extensions()

template<typename file_t = void>

static std::vector< std::string > seqan3::output_file_validator< file_t >::default_extensions ( )

inlinestatic

The default extensions of file_t.

Returns

A list of default extensions for file_t, will be empty if file_t is void.

If file_t does name a valid seqan3 file type that contains a static member valid_formats returns the extensions of that file_t type. Otherwise returns an empty list.

get_help_page_message()

template<typename file_t = void>

std::string seqan3::output_file_validator< file_t >::get_help_page_message ( ) const

inline

Returns a message that can be appended to the (positional) options help page info.

Implements validator.

operator()()

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

file	The input value to check.

Exceptions

seqan3::validation_error

if the validation process failed. Might be nested with std::filesystem::filesystem_error on unhandled OS API errors.

Implements seqan3::file_validator_base.

---

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

• validators.hpp