sharg::input_file_validator Class Reference

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

#include <sharg/validators.hpp>

Inheritance diagram for sharg::input_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 an existing regular file and is readable.
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
	input_file_validator ()=default
	Defaulted.
	input_file_validator (input_file_validator const &)=default
	Defaulted.
	input_file_validator (input_file_validator &&)=default
	Defaulted.
input_file_validator &	operator= (input_file_validator const &)=default
	Defaulted.
input_file_validator &	operator= (input_file_validator &&)=default
	Defaulted.
virtual	~input_file_validator ()=default
	Virtual destructor.
	input_file_validator (std::vector< std::string > extensions)
	Constructs from a given collection 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 input 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::filesystem::path) is not in the given list of valid file extensions, if the file does not exist, or if the file does not have the proper read permissions.

// 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
 
    std::filesystem::path myfile{};
 
    myparser.add_option(myfile,
                        sharg::config{.short_id = 'f',
                                      .long_id = "file",
                                      .description = "The input file containing the sequences.",
                                      .validator = sharg::input_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"] or if the file does not exist/is not readable.
    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::input_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>
 
#include <sharg/validators.hpp>
 
int main()
{
    // Default constructed validator has an empty extension list.
    sharg::input_file_validator validator1{};
    std::cerr << validator1.get_help_page_message() << '\n';
 
    // Specify your own extensions for the input file.
    sharg::input_file_validator validator2{std::vector{std::string{"exe"}, std::string{"fasta"}}};
    std::cerr << validator2.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

input_file_validator()

sharg::input_file_validator::input_file_validator ( std::vector< std::string > extensions )

inlineexplicit

Constructs from a given collection 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.

Member Function Documentation

get_help_page_message()

std::string sharg::input_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::input_file_validator::operator() ( std::filesystem::path const & file ) const

inlineoverridevirtual

Tests whether path is an existing regular file and is readable.

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