A functor whose operator() performs the server http request and version checks. More...

#include <seqan3/argument_parser/detail/version_check.hpp>

Public Member Functions
bool	decide_if_check_is_performed (update_notifications developer_approval, std::optional< bool > user_approval)
	The central decision whether to perform the version check or not.

void	operator() (std::promise< bool > prom)
	Initialises the version_checker with the application name and version.

Constructors, destructor and assignment
	version_checker ()=delete
	This class has to be initialised with name and version information.

	version_checker (version_checker const &)=default
	Defaulted.

version_checker &	operator= (version_checker const &)=default
	Defaulted.

	version_checker (version_checker &&)=default
	Defaulted.

version_checker &	operator= (version_checker &&)=default
	Defaulted.

	~version_checker ()=default
	Defaulted.

	version_checker (std::string name_, std::string const &version_, std::string const &app_url=std::string{})
	Initialises the version_checker with the application name and version.

Static Public Member Functions
static std::filesystem::path	get_path ()
	Returns a writable path to store timestamp and version files or an empty path if none exists.

Public Attributes
std::filesystem::path	cookie_path = get_path()
	The path to store timestamp and version files (either ~/.config/seqan or the tmp directory).

std::string	message_app_update
	The message directed to the user of the app if a new app version is available.

std::string	name
	The application name.

std::filesystem::path	timestamp_filename
	The timestamp filename.

std::string	version {"0.0.0"}
	The version of the application.

std::regex	version_regex {"^[[:digit:]]+\\.[[:digit:]]+\\.[[:digit:]]+$"}
	The regex to verify a valid version string.

Static Public Attributes
static constexpr char const *	home_env_name
	The environment name of the home environment used by getenv()

static constexpr std::string_view	message_registered_app_update
	The message directed to the developer if the application is registered but under a lower version.

static constexpr std::string_view	message_seqan3_update
	The message directed to the developer of the app if a new seqan3 version is available.

static constexpr std::string_view	message_unregistered_app
	The message directed to the developer of the app if the app is not yet registered with us.

static constexpr std::string_view	unregistered_app = "UNREGISTERED_APP"
	The identification string that may appear in the version file if an app is unregistered.

Private Member Functions
std::array< int, 3 >	get_numbers_from_version_string (std::string const &str) const
	Parses a version string into an array of length 3.

double	get_time_diff_to_current (std::string const &str_time) const
	Reads the timestamp file if possible and returns the time difference to the current time.

template<typename msg_type >
void	write_cookie (msg_type &&msg)
	Writes a cookie file with a specified message.

Static Private Member Functions
static std::string	get_program ()
	Returns the command line call as a std::string of an available program depending on the environment.

Detailed Description

A functor whose operator() performs the server http request and version checks.

Constructor & Destructor Documentation

◆ version_checker()

seqan3::detail::version_checker::version_checker	(	std::string	name_,
		std::string const &	version_,
		std::string const &	app_url = `std::string{}`
	)

inline

Initialises the version_checker with the application name and version.

Parameters

[in]	name_	The application name.
[in]	version_	The application version.
[in]	app_url	An (github) url with the newest release information of the application.

Member Function Documentation

◆ decide_if_check_is_performed()

bool seqan3::detail::version_checker::decide_if_check_is_performed	(	update_notifications	developer_approval,
		std::optional< bool >	user_approval
	)

inline

The central decision whether to perform the version check or not.

Parameters

[in]	developer_approval	Whether the developer approved (update_notifications::on) or not (update_notifications::off).
[in]	user_approval	Whether the user approved (true) or not (false) or did not decide (unset optional).

The following rules apply:

If the developer says no, it rules out all following decisions (even if the user specified –version-check true). No cookie is ever written.

If the environment variable SEQAN3_NO_VERSION_CHECK is set no version check is done (rules out all following). No cookie is written.

If the user explicitly uses the –version-check option (user_approval is set) it rules out all following decisions. No cookie is written.

If none of the above apply, version check was not explicitly handled so cookie content is checked:

NEVER: Do not perform the version check and do not change the cookie.
ALWAYS: Do perform the version check once a day and do not change the cookie.
ASK: Ask the user or default the decision once a day.

If the cookie content is "ASK" and the timestamp is older than a day we ask the user, if possible (seqan3::detail::is_terminal()), what he wants to do, set the according cookie for the next time and continue. If we cannot ask the user, the default kicks in (do the check).

◆ get_numbers_from_version_string()

std::array< int, 3 > seqan3::detail::version_checker::get_numbers_from_version_string ( std::string const & str ) const

inlineprivate

Parses a version string into an array of length 3.

Parameters

[in] str The version string that must match seqan3::detail::version_regex.

◆ operator()()

void seqan3::detail::version_checker::operator() ( std::promise< bool > prom )

inline

Initialises the version_checker with the application name and version.

Parameters

[in] prom The promise to track the state of the detached thread which calls seqan3::detail::call_server.

The operator performs the following steps:

If a timestamp file already exists, the following behaviour can be expected depending on the file contents:
- content "NEVER": No server call is performed and no update information is printed.
- content "ALWAYS": A server call is performed and update information is printed if a version file exists.
- content is a timestamp: The "time-of-last-version-check" is read from file. The function only continues if the last version check is more than a day old.
If a version file exists, the app version and seqan3 version are compared to the current ones and the the following message may be printed: Debug mode (directed at the developer of the application)
- If the app is unregistered (no version information is available at the server) the developer will be notified that he has the possibility of registering his application with us (see seqan3::version_checker::message_unregistered_app).
- If the current seqan version is smaller then the one returned by the server call, the developer is notified that he may update to the newest seqan3 version (see seqan3::version_checker::message_seqan3_update).
- If the current app version is greater than the one returned by the server call, we assume that the developer has released a new version and is notified to send us the new version (see seqan3::version_checker::message_registered_app_update). Release mode (directed at the user of the application):
- If the current app version is lower than the one returned by the server call, the user is notified that a newer version exists.

◆ write_cookie()

template<typename msg_type >

void seqan3::detail::version_checker::write_cookie ( msg_type && msg )

inlineprivate

Writes a cookie file with a specified message.

Template Parameters

msg_type The type of message.

Parameters

[in] msg The message to write into the file (no newline is appended).

Member Data Documentation

◆ home_env_name

constexpr char const* seqan3::detail::version_checker::home_env_name

staticconstexpr

Initial value:

{
 
        "HOME"
 
    }

The environment name of the home environment used by getenv()

◆ message_app_update

std::string seqan3::detail::version_checker::message_app_update

Initial value:

=
        "[APP INFO] :: A new version of this application is now available.\n"
        "[APP INFO] :: If you don't wish to receive further notifications, set --version-check false.\n\n"

The message directed to the user of the app if a new app version is available.

◆ message_registered_app_update

constexpr std::string_view seqan3::detail::version_checker::message_registered_app_update

staticconstexpr

Initial value:

=
        "[APP INFO] :: We noticed the app version you use is newer than the one registered with us.\n"
        "[APP INFO] :: Please send us an email with the new version so we can correct it (support@seqan.de)\n\n"

The message directed to the developer if the application is registered but under a lower version.

◆ message_seqan3_update

constexpr std::string_view seqan3::detail::version_checker::message_seqan3_update

staticconstexpr

Initial value:

=
        "[SEQAN3 INFO] :: A new SeqAn version is available online.\n"
        "[SEQAN3 INFO] :: Please visit www.github.com/seqan/seqan3.git for an update\n"
        "[SEQAN3 INFO] :: or inform the developer of this app.\n"
        "[SEQAN3 INFO] :: If you don't wish to receive further notifications, set --version-check false.\n\n"

The message directed to the developer of the app if a new seqan3 version is available.

◆ message_unregistered_app

constexpr std::string_view seqan3::detail::version_checker::message_unregistered_app

staticconstexpr

Initial value:

=
        "[SEQAN3 INFO] :: Thank you for using SeqAn!\n"
        "[SEQAN3 INFO] :: Do you wish to register your app for update notifications?\n"
        "[SEQAN3 INFO] :: Just send an email to support@seqan.de with your app name and version number.\n"
        "[SEQAN3 INFO] :: If you don't wish to receive further notifications, set --version-check false.\n\n"

The message directed to the developer of the app if the app is not yet registered with us.

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

version_check.hpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Static Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ version_checker()

Member Function Documentation

◆ decide_if_check_is_performed()

◆ get_numbers_from_version_string()

◆ operator()()

◆ write_cookie()

Member Data Documentation

◆ home_env_name

◆ message_app_update

◆ message_registered_app_update

◆ message_seqan3_update

◆ message_unregistered_app