sharg::detail::version_checker Class Reference

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.

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

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.

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:

1. 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.
2. 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_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