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

#include <sharg/detail/version_check.hpp>

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

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.

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.

static bool	is_disabled (update_notifications developer_approval, std::optional< bool > user_approval)
	Whether the developer, the environment variable SHARG_NO_VERSION_CHECK or the user disabled the check.

Public Attributes
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::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.

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

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

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

static constexpr std::string_view	message_sharg_update
	The message directed to the developer of the app if a new sharg 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	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_no_writable_directory
	The message if the version check is skipped because there is no writable directory for its files.

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

Private Member Functions
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.

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

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()

sharg::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 sharg::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 SHARG_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. However, if there is no writable directory (see get_path()), no version check is done even if the user specified –version-check true. If the terminal is interactive, message_no_writable_directory is printed instead.

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, 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 > sharg::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 sharg::detail::version_regex.

◆ get_path()

static std::filesystem::path sharg::detail::version_checker::get_path ( )

inlinestatic

Returns a writable path to store timestamp and version files or an empty path if none exists.

The path is .config/seqan in the home directory given by the environment variable HOME (UserProfile on Windows). If this variable is not set or empty, .config/seqan is relative to the current working directory. If .config/seqan cannot be created, the temporary directory is used, see std::filesystem::temp_directory_path.

◆ is_disabled()

static bool sharg::detail::version_checker::is_disabled	(	update_notifications	developer_approval,
		std::optional< bool >	user_approval )

inlinestatic

Whether the developer, the environment variable SHARG_NO_VERSION_CHECK or the user disabled the check.

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).

In contrast to decide_if_check_is_performed(), this does not need the directory for the timestamp and version files. Hence, the parser can call it before constructing the version_checker, which determines and creates this directory.

◆ operator()()

void sharg::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 sharg::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 Sharg 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 sharg::version_checker::message_unregistered_app).
- If the current Sharg version is smaller than the one returned by the server call, the developer is notified that he may update to the newest Sharg version (see sharg::version_checker::message_sharg_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 sharg::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 sharg::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* sharg::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 sharg::detail::version_checker::message_app_update

Initial value:

=
        "[APP VERSION INFO] :: A new version of this application is now available.\n"
        "[APP VERSION 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_no_writable_directory

constexpr std::string_view sharg::detail::version_checker::message_no_writable_directory

staticconstexpr

Initial value:

=
        "[SHARG VERSION INFO] :: The version check was skipped because there is no writable directory for its files.\n"
        "[SHARG VERSION INFO] :: For details, see "
        "https://docs.seqan.de/sharg/main_user/about_update_notifications.html\n"
        "[SHARG VERSION INFO] :: If you don't wish to receive further notifications, set --version-check false.\n\n"

The message if the version check is skipped because there is no writable directory for its files.

◆ message_registered_app_update

constexpr std::string_view sharg::detail::version_checker::message_registered_app_update

staticconstexpr

Initial value:

=
        "[APP VERSION INFO] :: We noticed the app version you use is newer than the one registered with us.\n"
        "[APP VERSION 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_sharg_update

constexpr std::string_view sharg::detail::version_checker::message_sharg_update

staticconstexpr

Initial value:

=
        "[SHARG VERSION INFO] :: A new Sharg version is available online.\n"
        "[SHARG VERSION INFO] :: Please visit www.github.com/seqan/sharg-parser.git for an update\n"
        "[SHARG VERSION INFO] :: or inform the developer of this app.\n"
        "[SHARG VERSION 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 sharg version is available.

◆ message_unregistered_app

constexpr std::string_view sharg::detail::version_checker::message_unregistered_app

staticconstexpr

Initial value:

=
        "[SHARG VERSION INFO] :: Thank you for using Sharg!\n"
        "[SHARG VERSION INFO] :: Do you wish to register your app for update notifications?\n"
        "[SHARG VERSION INFO] :: Just send an email to support@seqan.de with your app name and version number.\n"
        "[SHARG VERSION 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()

◆ get_path()

◆ is_disabled()

◆ operator()()

◆ write_cookie()

Member Data Documentation

◆ home_env_name

◆ message_app_update

◆ message_no_writable_directory

◆ message_registered_app_update

◆ message_sharg_update

◆ message_unregistered_app