scriptModules.hpp File Reference

Modules that run shell scripts. More...

#include <string>
#include <condition_variable>
#include <chrono>
#include <functional>
#include <memory>
#include <mutex>
#include <filesystem>

Include dependency graph for scriptModules.hpp:

Go to the source code of this file.

Classes
class	PSSspace::TimedModule
	A module executed on a timer. More...
class	PSSspace::SignalModule
	A module executed on a signal. More...

Typedefs
using	PSSspace::MessageTranslator = std::function<std::string(const std::string &messageId, const std::string &argument)>
	User-facing message translator hook.

Functions
void	PSSspace::setMessageTranslator (MessageTranslator translator)
	Install the user-facing message translator.
std::string	PSSspace::translateMessage (const std::string &messageId, const std::string &argument)
	Translate a user-facing backend message.
std::string	PSSspace::runScript (const std::filesystem::path &script)
	Run a script once.
void	PSSspace::truncateUtf8 (std::string &text, size_t maxCodepoints)
	Truncate a UTF-8 string to a codepoint limit, in place.

Detailed Description

Modules that run shell scripts.

Author

Anthony J. Greenberg

Copyright

Copyright (c) 2026 Anthony J. Greenberg

Version

0.1.0

API definitions to manage named shell script execution.

Typedef Documentation

MessageTranslator

using PSSspace::MessageTranslator = std::function<std::string(const std::string &messageId, const std::string &argument)>

User-facing message translator hook.

Maps a stable message identifier and its single argument to the localized, user-facing string. Kept as a std::function so the module layer stays free of Qt/KI18n: the Qt bridge installs a translator backed by i18n(), while the default (and the pure-C++ tests) fall back to English. See setMessageTranslator and translateMessage.

Parameters

[in]	messageId	stable identifier of the message
[in]	argument	the message's single substituted argument

Returns

localized message

Function Documentation

runScript()

std::string PSSspace::runScript ( const std::filesystem::path & script )

nodiscard

Run a script once.

Runs a shell script and return the output.

Parameters

[in]

script

path to the script

Returns

string output

setMessageTranslator()

void PSSspace::setMessageTranslator

(

MessageTranslator

translator

)

Install the user-facing message translator.

Replaces the process-wide translator used by translateMessage. The Qt bridge calls this once at construction with a translator backed by i18n(); if never called (e.g. in the Qt-free unit tests) the built-in English default is used. A null translator is ignored. Thread-safe.

Parameters

[in]

translator

translator to install

translateMessage()

std::string PSSspace::translateMessage ( const std::string & messageId, const std::string & argument )

nodiscard

Translate a user-facing backend message.

Looks up the currently installed translator (see setMessageTranslator) and applies it to messageId/argument. Thread-safe; the translator is copied under a lock and invoked outside it, so a worker thread can translate while the bridge installs its translator.

Parameters

[in]	messageId	stable identifier of the message
[in]	argument	the message's single substituted argument

Returns

localized message

truncateUtf8()

void PSSspace::truncateUtf8	(	std::string &	text,
		size_t	maxCodepoints )

Truncate a UTF-8 string to a codepoint limit, in place.

Shortens text to at most maxCodepoints Unicode codepoints, cutting only on a codepoint boundary so a multi-byte UTF-8 sequence is never split (which would otherwise leave an invalid trailing byte that renders as the replacement character). For ASCII this is identical to a byte truncation. Leaves text unchanged if it already fits. Malformed lead/continuation bytes are each counted as one codepoint so the function always makes progress and degrades gracefully. The module layer's output limit is expressed in characters (codepoints), matching the Plasma config UI.

Parameters

[in,out]	text	UTF-8 string to truncate in place
[in]	maxCodepoints	maximum number of codepoints to keep