Detailed Description

A class for listing, loading, storing, and renaming sequences in a given file system directory.

// Create a SequenceManager that manages sequences stored in the base folder "sequences"
SequenceManager manager{ "sequences" };
 
// List all sequences below the base folder
auto sequences = manager.list_sequences();
 
for (const auto& s : sequences) {
    // Load the sequence from disk
    auto seq = manager.load_sequence(s.path);
    std::cout << "Sequence " << seq.get_name() << " has " << seq.get_steps().size()
              << " steps\n";
}

#include <SequenceManager.h>

Classes
struct	SequenceOnDisk
	A struct to represent a sequence on disk. More...

Public Member Functions
	SequenceManager (std::filesystem::path path)
	Create a SequenceManager to manage sequences that are stored in a given directory. More...

Sequence	copy_sequence (UniqueId original_uid, const SequenceName &new_name)
	Create a copy of an existing sequence (from disk). More...

Sequence	create_sequence (gul14::string_view label="", SequenceName name=SequenceName{})
	Create an empty sequence on disk. More...

std::filesystem::path	get_path () const
	Return the base path of the serialized sequences. More...

Sequence	import_sequence (const std::filesystem::path &path)
	Import a sequence from a folder, assigning a new unique ID to it. More...

std::vector< SequenceOnDisk >	list_sequences () const
	Return an unsorted list of all valid sequences that are found in the base path. More...

Sequence	load_sequence (UniqueId uid) const
	Load a sequence from the base folder. More...

Sequence	load_sequence (UniqueId uid, const std::vector< SequenceOnDisk > &sequences) const

Sequence	load_sequence (std::filesystem::path folder) const
	Load a sequence from an arbitrary folder on disk. More...

void	remove_sequence (UniqueId unique_id)
	Remove a sequence from the base folder. More...

void	rename_sequence (UniqueId unique_id, const SequenceName &new_name)
	Change the machine-friendly name of a sequence on disk. More...

void	rename_sequence (Sequence &sequence, const SequenceName &new_name)
	Change the machine-friendly name of a sequence, both in a Sequence object and on disk. More...

bool	store_sequence (const Sequence &sequence)
	Store the given sequence in a subfolder under the base directory of this object. More...

Static Public Member Functions
static gul14::optional< SequenceOnDisk >	parse_folder_name (const std::filesystem::path &folder)
	Determine the name and unique ID of a sequence from a folder name, if possible. More...

Private Member Functions
Sequence	load_sequence (const SequenceOnDisk &seq_on_disk) const
	Load a sequence from the specified path, with the given name and unique ID. More...

template<typename T >
bool	perform_commit (std::string message, T action, std::string extra_dir="")
	Perform changes and commit them to the git repository. More...

std::string	stage_files_in_directory (const std::string &directory)
	Stage all changes to files in the given directory for the next git commit. More...

std::string	stage_files (const std::string &glob)
	Stage files matching the specified glob for the next git commit. More...

std::string	write_sequence_to_disk (const Sequence &sequence)
	Actually write a sequence to disk (without commit in git) More...

Static Private Member Functions
static UniqueId	create_unique_id (const std::vector< SequenceOnDisk > &sequences)
	Create a random unique ID that does not collide with the ID of any sequence in the given sequence list. More...

static SequenceOnDisk	find_sequence_on_disk (UniqueId uid, const std::vector< SequenceOnDisk > &sequences)
	Find the sequence with the given unique ID in the given list of sequences. More...

static SequenceName	make_sequence_name_from_label (gul14::string_view label)
	Generate a machine-friendly sequence name from a human-readable label. More...

Private Attributes
std::filesystem::path	path_
	Base path to the sequences. More...

git::Repository	git_repo_
	Git repository in path_ that holds the sequences. More...

Constructor & Destructor Documentation

◆ SequenceManager()

task::SequenceManager::SequenceManager ( std::filesystem::path path )

explicit

Create a SequenceManager to manage sequences that are stored in a given directory.

Parameters

path	the base folder that contains individual folders for each sequence.

Exceptions

Error is thrown if the path name is empty.

References path_.

Member Function Documentation

◆ copy_sequence()

Sequence task::SequenceManager::copy_sequence	(	UniqueId	original_uid,
		const SequenceName &	new_name
	)

Create a copy of an existing sequence (from disk).

This function loads an existing sequence (identified by its unique ID) from disk, assigns a new name (new_name) and a new random unique ID to it, and stores the new sequence in the base folder.

Parameters

original_uid	Unique ID of the original sequence
new_name	Machine-friendly name of the copy

Returns: the copied sequence as if it had been loaded from disk.

Exceptions

Error is thrown if the original sequence cannot be found or if the new sequence folder cannot be created.

References create_unique_id(), find_sequence_on_disk(), list_sequences(), load_sequence(), task::SequenceManager::SequenceOnDisk::path, perform_commit(), and task::to_string().

◆ create_sequence()

Sequence task::SequenceManager::create_sequence	(	gul14::string_view	label = `""`,
		SequenceName	name = `SequenceName{}`
	)

Create an empty sequence on disk.

The new sequence contains no steps and has a randomly assigned unique ID.

Parameters

label	An optional human-readable label for the sequence
name	A optional machine-friendly name for the sequence

Returns: a new sequence.

Exceptions

Error is thrown if the sequence folder cannot be created.

References create_unique_id(), list_sequences(), perform_commit(), task::to_string(), and write_sequence_to_disk().

◆ create_unique_id()

UniqueId task::SequenceManager::create_unique_id ( const std::vector< SequenceOnDisk > & sequences )

staticprivate

Create a random unique ID that does not collide with the ID of any sequence in the given sequence list.

Exceptions

Error is thrown if no unique ID can be found.

Referenced by copy_sequence(), create_sequence(), and import_sequence().

◆ find_sequence_on_disk()

SequenceManager::SequenceOnDisk task::SequenceManager::find_sequence_on_disk	(	UniqueId	uid,
		const std::vector< SequenceOnDisk > &	sequences
	)

staticprivate

Find the sequence with the given unique ID in the given list of sequences.

Exceptions

Error is thrown if the sequence cannot be found.

References task::to_string().

Referenced by copy_sequence(), load_sequence(), remove_sequence(), and rename_sequence().

◆ get_path()

std::filesystem::path task::SequenceManager::get_path ( ) const

inline

Return the base path of the serialized sequences.

Returns: the base path of the serialized sequences.

References path_.

◆ import_sequence()

Sequence task::SequenceManager::import_sequence ( const std::filesystem::path & path )

Import a sequence from a folder, assigning a new unique ID to it.

This function loads an existing sequence from the specified path. If the import is successful, the new sequence is stored in the base folder. It keeps the name and label of the original, but a random unique ID is assigned.

Parameters

path	Path to the original sequence folder

Returns: the copied sequence as if it had been loaded from disk.

Exceptions

Error is thrown if the original sequence cannot be loaded or if the new sequence folder cannot be created.

References create_unique_id(), list_sequences(), load_sequence(), perform_commit(), and task::to_string().

◆ list_sequences()

std::vector< SequenceManager::SequenceOnDisk > task::SequenceManager::list_sequences ( ) const

Return an unsorted list of all valid sequences that are found in the base path.

This function quietly ignores folders that do not follow the naming convention for sequences.

Returns: a vector containing one SequenceOnDisk object for each sequence that was found. The paths in the returned objects are relative to the base path.

References task::SequenceManager::SequenceOnDisk::name, parse_folder_name(), and path_.

Referenced by copy_sequence(), create_sequence(), import_sequence(), load_sequence(), remove_sequence(), and rename_sequence().

◆ load_sequence() [1/4]

Sequence task::SequenceManager::load_sequence ( const SequenceOnDisk & seq_on_disk ) const

private

Load a sequence from the specified path, with the given name and unique ID.

References task::load_sequence_parameters(), task::load_step(), task::SequenceManager::SequenceOnDisk::name, task::SequenceManager::SequenceOnDisk::path, path_, and task::SequenceManager::SequenceOnDisk::unique_id.

◆ load_sequence() [2/4]

Sequence task::SequenceManager::load_sequence ( std::filesystem::path folder ) const

Load a sequence from an arbitrary folder on disk.

This function can be used to load a sequence from a folder that is not managed by the SequenceManager. The machine-friendly name and unique ID of the sequence are parsed from its folder name.

Parameters

folder The sequence folder to be loaded

Exceptions

Error is thrown if the sequence cannot be loaded.

References load_sequence(), and parse_folder_name().

◆ load_sequence() [3/4]

Sequence task::SequenceManager::load_sequence ( UniqueId uid ) const

Load a sequence from the base folder.

Parameters

unique_id unique ID of the sequence to be loaded

Returns: the loaded sequence.

Exceptions

Error is thrown if the sequence cannot be loaded.

References list_sequences().

Referenced by copy_sequence(), import_sequence(), and load_sequence().

◆ load_sequence() [4/4]

Sequence task::SequenceManager::load_sequence	(	UniqueId	uid,
		const std::vector< SequenceOnDisk > &	sequences
	)		const

This overload allows to pass in a list of sequences to avoid having to examine the base path again:

Parameters

sequences a list of sequences as obtained from list_sequences()

References find_sequence_on_disk(), and load_sequence().

◆ make_sequence_name_from_label()

SequenceName task::SequenceManager::make_sequence_name_from_label ( gul14::string_view label )

staticprivate

Generate a machine-friendly sequence name from a human-readable label.

References task::SequenceName::max_length, and task::SequenceName::valid_characters.

◆ parse_folder_name()

gul14::optional< SequenceManager::SequenceOnDisk > task::SequenceManager::parse_folder_name ( const std::filesystem::path & folder )

static

Determine the name and unique ID of a sequence from a folder name, if possible.

Taskolib stores sequences in a folder following the scheme "name[uid]". This function extracts the final folder name from the given path and splits it into name and unique ID. If the folder does not follow the naming scheme, nullopt is returned.

References task::SequenceName::from_string(), and task::UniqueId::from_string().

Referenced by list_sequences(), and load_sequence().

◆ perform_commit()

template<typename T >

bool task::SequenceManager::perform_commit	(	std::string	message,
		T	action,
		std::string	extra_dir = `""`
	)

inlineprivate

Perform changes and commit them to the git repository.

This function allows to introduce some changes to the filesystem and create a git commit from the changes; but if something fails the repository is rolled back safely.

Committed are just changes in the directories given in dirs and the message starts with the specified message. Both dirs and message can be extended by the actual actions that are performed.

Repository is prepared (reset)
The actions are performed (closure is executed) - they should change the filesystem
Git searches for changes (just in the directories given by dirs)
The changes are added and committed using the given message as title
The commit body contains details about the changed files
If at any point an error occurs the commit is aborted and the filesystem is reset to where we started (changes are undone)

Sometimes we do not know the actual path we want change and commit before the real actions are performed. The closure can return a string; and that is a path to be also considered/added to the commit. The path as string is also added at the end of the title.

The signature of the closure can be void action() or std::string action().

It is not possible to add a path to dirs while keeping the commit title unchanged.

All dirs are relative to the git repository root.

Parameters

dirs	List of directories to add for this commit (usually just one)
message	The commit message title
action	Closure that performs the actual modifications on the filesystem

Returns: true if the commit was successful, false if nothing found to commit

Exceptions

task::Error,git::Error,or any other type can be thrown

References git_repo_, and stage_files_in_directory().

Referenced by copy_sequence(), create_sequence(), import_sequence(), remove_sequence(), and rename_sequence().

◆ remove_sequence()

void task::SequenceManager::remove_sequence ( UniqueId unique_id )

Remove a sequence from the base folder.

The sequence to be removed is identified by its unique ID.

Parameters

unique_id the unique ID of the sequence

Exceptions

Error is thrown if the sequence cannot be found or if the removal of the folder fails.

References find_sequence_on_disk(), list_sequences(), path_, perform_commit(), and task::to_string().

◆ rename_sequence() [1/2]

void task::SequenceManager::rename_sequence	(	Sequence &	sequence,
		const SequenceName &	new_name
	)

Change the machine-friendly name of a sequence, both in a Sequence object and on disk.

The sequence to be renamed is identified by the unique ID of the given Sequence object. The Sequence object is updated to reflect the new name.

Parameters

sequence	the sequence to be renamed
new_name	the new machine-friendly name of the sequence

Exceptions

Error is thrown if the sequence cannot be found or if the renaming of the folder fails.

References task::Sequence::get_unique_id(), and task::Sequence::set_name().

◆ rename_sequence() [2/2]

void task::SequenceManager::rename_sequence	(	UniqueId	unique_id,
		const SequenceName &	new_name
	)

Change the machine-friendly name of a sequence on disk.

The sequence to be renamed is identified by its unique ID.

Parameters

unique_id	the unique ID of the sequence
new_name	the new machine-friendly name of the sequence

Exceptions

Error is thrown if the sequence cannot be found or if the renaming of the folder fails.

References find_sequence_on_disk(), list_sequences(), task::make_sequence_filename(), and perform_commit().

◆ stage_files()

std::string task::SequenceManager::stage_files ( const std::string & glob )

private

Stage files matching the specified glob for the next git commit.

This function is similar to "git add", but it can also stage files for removal like "git rm".

Parameters

glob	A git glob specifying which files to stage. If it is empty, all files in the repository are considered. Examples: "", "*.txt", "foo/backup_[0-9].dat"

Returns: a partial commit message containing information about the staged changes. The returned string starts with a linebreak.

◆ stage_files_in_directory()

std::string task::SequenceManager::stage_files_in_directory ( const std::string & directory )

private

Stage all changes to files in the given directory for the next git commit.

This function is similar to "git add", but it can also stage files for removal like "git rm". It recursively stages all changes to files in the given directory and in its subdirectories.

Parameters

directory Directory whose contents should be staged. Glob/wildcard characters like '*' or '?' are considered a literal part of the directory name and escaped automatically.

Returns: a partial commit message containing information about the staged changes. The returned string starts with a linebreak.

Referenced by perform_commit().

◆ store_sequence()

bool task::SequenceManager::store_sequence ( const Sequence & sequence )

Store the given sequence in a subfolder under the base directory of this object.

This function generates a subfolder name from the sequence name and unique ID. If such a subfolder exists already, it is removed. Afterwards, a subfolder is newly created and the sequence is stored inside it. Inside the folder, each step is stored in a separate file. The filenames start with step followed by a consecutive number followed by the type of the step and the extension ‘’.lua'`. The step number is zero-filled to allow alphanumerical sorting (e.g. step_01_action.lua). This function uses git.

Parameters

sequence the sequence to be stored

Returns: True if the sequence has been stored or false if it was unmodified

Exceptions

git::Error is thrown if git could not handle the operation

◆ write_sequence_to_disk()

std::string task::SequenceManager::write_sequence_to_disk ( const Sequence & sequence )

private

Actually write a sequence to disk (without commit in git)

Parameters

sequence Sequence object to save

Returns: Folder of the sequence on disk (relative to path_)

References task::Sequence::get_folder(), task::sequence_lua_filename, task::Sequence::size(), and task::store_step().

Referenced by create_sequence().

Member Data Documentation

◆ git_repo_

git::Repository task::SequenceManager::git_repo_

private

Git repository in path_ that holds the sequences.

Referenced by perform_commit().

◆ path_

std::filesystem::path task::SequenceManager::path_

private

Base path to the sequences.

Referenced by get_path(), list_sequences(), load_sequence(), remove_sequence(), and SequenceManager().

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

Detailed Description

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ SequenceManager()

Member Function Documentation

◆ copy_sequence()

◆ create_sequence()

◆ create_unique_id()

◆ find_sequence_on_disk()

◆ get_path()

◆ import_sequence()

◆ list_sequences()

◆ load_sequence() [1/4]

◆ load_sequence() [2/4]

◆ load_sequence() [3/4]

◆ load_sequence() [4/4]

◆ make_sequence_name_from_label()

◆ parse_folder_name()

◆ perform_commit()

◆ remove_sequence()

◆ rename_sequence() [1/2]

◆ rename_sequence() [2/2]

◆ stage_files()

◆ stage_files_in_directory()

◆ store_sequence()

◆ write_sequence_to_disk()

Member Data Documentation

◆ git_repo_

◆ path_