sharg::output_file_validator Class Reference

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

#include <sharg/validators.hpp>

Inheritance diagram for sharg::output_file_validator:

Public Types
using	option_value_type
	Type of values that are tested by validator.
Public Types inherited from sharg::file_validator_base
using	option_value_type = std::string
	Type of values that are tested by validator.

Public Member Functions
virtual void	operator() (std::filesystem::path const &file) const override
	Tests whether path is does not already exists and is writable.
std::string	get_help_page_message () const
	Returns a message that can be appended to the (positional) options help page info.
Constructors, destructor and assignment
	output_file_validator ()=default
	Defaulted.
	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)
	Constructs from a given overwrite mode and a list of valid extensions.
	output_file_validator (output_file_open_options const mode, auto &&... extensions)
	Constructs from a given overwrite mode and a parameter pack of valid extensions.
	output_file_validator (std::vector< std::string > const &extensions)
	Constructs from a list of valid extensions.
	output_file_validator (auto &&... extensions)
	Constructs from a parameter pack 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 sharg::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

Additional Inherited Members
Protected Member Functions inherited from sharg::file_validator_base
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.
std::string	valid_extensions_help_page_message () const
	Returns the information of valid file extensions.
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.
Protected Attributes inherited from sharg::file_validator_base
std::vector< std::string >	extensions {}
	Stores the extensions.
std::string	extensions_str {}
	The extension range as a std:;string for pretty printing.

Detailed Description

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

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 sharg::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 sharg::output_file_open_options which allows you to specify what to do if your output file already exists. sharg::output_file_open_options::create_new will throw a sharg::validation_error exception if it already exists and sharg::output_file_open_options::open_or_create will skip this check (that means you are allowed to overwrite the existing file). The validator itself does not modify an existing file.

// SPDX-FileCopyrightText: 2006-2026 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2026 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <sharg/all.hpp>
 
int main(int argc, char const ** argv)
{
    sharg::parser myparser{"Test", argc, argv}; // initialize
 
    std::filesystem::path myfile{};
 
    // Use the sharg::output_file_open_options to indicate that you allow overwriting existing output files, ...
    myparser.add_option(
        myfile,
        sharg::config{.short_id = 'f',
                      .long_id = "file",
                      .description = "Output file containing the processed sequences.",
                      .validator = sharg::output_file_validator{sharg::output_file_open_options::open_or_create,
                                                                {"fa", "fasta"}}});
 
    // ... or that you will throw a sharg::validation_error if the user specified output file already exists
    // No sharg::output_file_open_options is passed: The default sharg::output_file_open_options::create_new is used.
    // Possible extensions can also be passed as separate arguments.
    myparser.add_option(myfile,
                        sharg::config{.short_id = 'g',
                                      .long_id = "file2",
                                      .description = "Output file containing the processed sequences.",
                                      .validator = sharg::output_file_validator{"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 (sharg::parser_error const & ext) // the user did something wrong
    {
        std::cerr << "[PARSER ERROR] " << ext.what() << "\n"; // customize your error message
        return -1;
    }
 
    std::cerr << "filename given by user passed validation: " << myfile << "\n";
    return 0;
}

The following snippet demonstrates the different ways to instantiate the sharg::output_file_validator.

// SPDX-FileCopyrightText: 2006-2026 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2026 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <iostream>
 
#include <sharg/validators.hpp>
 
int main()
{
    // Default constructed validator has an empty extension list.
    sharg::output_file_validator validator1{};
    std::cerr << validator1.get_help_page_message() << '\n';
 
    // Specify your own extensions for the output file.
    sharg::output_file_validator validator2{sharg::output_file_open_options::create_new,
                                            std::vector{std::string{"exe"}, std::string{"fasta"}}};
    std::cerr << validator2.get_help_page_message() << '\n';
 
    // If you do not pass the output_file_open_options, the default of create_new is used.
    sharg::output_file_validator validator3{std::vector{std::string{"exe"}, std::string{"fasta"}}};
    std::cerr << validator3.get_help_page_message() << '\n';
 
    // Instead of passing a std::vector<std::string>, you can also pass each extension as separate argument.
    sharg::output_file_validator validator4{"exe", "fasta"};
    std::cerr << validator4.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 Parser

This entity is experimental and subject to change in the future. Experimental since version 1.0.

Constructor & Destructor Documentation

output_file_validator() [1/4]

sharg::output_file_validator::output_file_validator ( output_file_open_options const mode, std::vector< std::string > extensions )

inlineexplicit

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

Parameters

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

This entity is experimental and subject to change in the future. Experimental since version 1.0.

output_file_validator() [2/4]

sharg::output_file_validator::output_file_validator ( output_file_open_options const mode, auto &&... extensions )

inlineexplicit

Constructs from a given overwrite mode and a parameter pack of valid extensions.

Parameters

[in]	mode	A sharg::output_file_open_options indicating whether the validator throws if a file already exists.
[in]	extensions	Parameter pack representing valid extensions. std::string must be constructible from each argument. The pack may be empty ( → all extensions are valid).

This entity is experimental and subject to change in the future. Experimental since version 1.0.

output_file_validator() [3/4]

sharg::output_file_validator::output_file_validator ( std::vector< std::string > const & extensions )

inlineexplicit

Constructs from a list of valid extensions.

Parameters

[in]

extensions

The valid extensions to validate for.

This entity is experimental and subject to change in the future. Experimental since version 1.0.

output_file_validator() [4/4]

sharg::output_file_validator::output_file_validator ( auto &&... extensions )

inlineexplicit

Constructs from a parameter pack of valid extensions.

Parameters

[in]

extensions

Parameter pack representing valid extensions. std::string must be constructible from each argument. The pack may be empty ( → all extensions are valid).

This entity is experimental and subject to change in the future. Experimental since version 1.0.

Member Function Documentation

get_help_page_message()

std::string sharg::output_file_validator::get_help_page_message ( ) const

inline

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

This entity is experimental and subject to change in the future. Experimental since version 1.0.

operator()()

virtual void sharg::output_file_validator::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

sharg::validation_error

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

This entity is experimental and subject to change in the future. Experimental since version 1.0.

Implements sharg::file_validator_base.

---

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

• validators.hpp