Sharg 1.1.2-rc.1
The argument parser for bio-c++ tools.
Loading...
Searching...
No Matches
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_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 (output_file_open_options const mode, std::vector< std::string > const &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_baseoperator= (file_validator_base const &)=default
 Defaulted.
 
file_validator_baseoperator= (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::stringextensions {}
 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).

// 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 <sharg/all.hpp>
int main(int argc, char const ** argv)
{
sharg::parser myparser{"Test", argc, argv}; // initialize
// Use the sharg::output_file_open_options to indicate that you allow overwriting existing output files, ...
myparser.add_option(
myfile,
.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,
.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;
}
Meta-header for the Parser module .
A validator that checks if a given path is a valid output file.
Definition validators.hpp:640
Parser exception that is thrown whenever there is an error while parsing the command line arguments.
Definition exceptions.hpp:40
The Sharg command line parser.
Definition parser.hpp:154
Option struct that is passed to the sharg::parser::add_option() function.
Definition config.hpp:43
char short_id
The short identifier for the option (e.g. 'a', making the option callable via -a).
Definition config.hpp:53
T what(T... args)

The following snippet demonstrates the different ways to instantiate the sharg::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 <iostream>
int main()
{
// Default constructed validator has an empty extension list.
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.
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;
}
Provides some standard validators for (positional) options.
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 > const & extensions )
inlineexplicit

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

Parameters
[in]modeA sharg::output_file_open_options indicating whether the validator throws if a file already exists.
[in]extensionsThe 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]modeA sharg::output_file_open_options indicating whether the validator throws if a file already exists.
[in]extensionsParameter 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]extensionsThe 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]extensionsParameter 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
fileThe input value to check.
Exceptions
sharg::validation_errorif 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:
Hide me