This class represents a symbolic link on the filesystem. More...

#include <lfilesystem_SymLink.h>

Inheritance diagram for limes::files::SymLink:

Public Member Functions
	SymLink (const Path &symLinkPath, const FilesystemEntry &linkTarget)
	Creates a symbolic link object (the link itself will also be created on the filesystem). More...

	SymLink (const SymLink &)=default

	SymLink (SymLink &&)=default

	FilesystemEntry ()=default
	Creates a FilesystemEntry with an empty path. More...

	FilesystemEntry (const FilesystemEntry &)=default

	FilesystemEntry (const Path &pathToUse)
	Creates a FilesystemEntry referring to the specified path. More...

	FilesystemEntry (FilesystemEntry &&)=default

FilesystemEntry	follow (std::size_t recursionDepth=50) const noexcept
	Follows the symbolic link to find its target. More...

bool	isDangling () const noexcept
	Returns true if this symbolic link's target does not exist. More...

bool	isDirectory () const noexcept final
	Returns true if this filesystem entry refers to a directory. More...

bool	isFile () const noexcept final
	Returns true if this filesystem entry refers to a file. More...

bool	isSymLink () const noexcept final
	Returns true if this filesystem entry refers to a symbolic link. More...

SymLink &	operator= (const SymLink &)=default

SymLink &	operator= (SymLink &&)=default

bool	references (const FilesystemEntry &entry, std::size_t recursionDepth=50) const noexcept
	Returns true if this symbolic link references the given FilesystemEntry, either as its immediate target or as part of the chain of recursive symbolic links (if one exists). More...

bool	referencesSameLocationAs (const SymLink &other) const
	Returns true if the other symbolic link references the same target as this one, either as its immediate target or as part of the chain of recursive symbolic links (if one exists). More...

Public Member Functions inherited from limes::files::FilesystemEntry
	FilesystemEntry (const FilesystemEntry &)=default

	FilesystemEntry (FilesystemEntry &&)=default

virtual	~FilesystemEntry ()=default
	Destructor. More...

bool	copyFrom (const FilesystemEntry &source, CopyOptions options=CopyOptions::update_existing) const noexcept

bool	copyFrom (const Path &source, CopyOptions options=CopyOptions::update_existing) const noexcept
	Overwriting. More...

FilesystemEntry &	operator= (const FilesystemEntry &)=default

FilesystemEntry &	operator= (FilesystemEntry &&)=default

bool	revealToUserInFileBrowser () const
	Uses the system's native file browser to display this file to the user. More...

	FilesystemEntry ()=default
	Creates a FilesystemEntry with an empty path. More...

	FilesystemEntry (const Path &pathToUse)
	Creates a FilesystemEntry referring to the specified path. More...

FilesystemEntry &	operator= (const Path &newPath)
	Assigns the path this filesystem entry represents. More...

FilesystemEntry &	operator= (const std::string_view &newPath)
	Assigns the path this filesystem entry represents. More...

FilesystemEntry &	assignPath (const Path &newPath) noexcept
	Assigns the path this filesystem entry represents. More...

bool	operator== (const FilesystemEntry &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator== (const Path &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator!= (const FilesystemEntry &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator!= (const Path &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator< (const FilesystemEntry &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

bool	operator> (const FilesystemEntry &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

bool	operator< (const Path &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

bool	operator> (const Path &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

FilesystemEntry	operator/ (const std::string_view &subpathName) const
	Returns a new FilesystemEntry referring to a subpath of this one. More...

FilesystemEntry &	operator/= (const std::string_view &subpathName)
	Assigns this object's path to a subpath of the current path. More...

FilesystemEntry &	changeName (const std::string_view &newName)
	Changes the last section of the path (the filename). More...

bool	makeAbsoluteRelativeTo (const Path &basePath) noexcept
	If the path this object holds is already absolute, this function does nothing and returns false. More...

bool	makeAbsoluteRelativeToCWD () noexcept
	Similar to `makeAbsoluteRelativeTo()`, but uses the current working directory as the base path. More...

Path	getPath (bool makePreferred=false) const noexcept
	Returns the current path held by this object. More...

Path	getAbsolutePath (bool makePreferred=false) const noexcept
	Returns the full, absolute path of this filesystem entry. More...

	operator Path () const noexcept
	Converts this filesystem entry to the path it holds. More...

std::string	getName () const noexcept
	Returns the last section of the path (the filename). More...

Directory	getDirectory () const
	Returns the directory containing this filesystem entry. More...

Directory	getParentDirectory () const
	Returns the parent directory of this filesystem entry. More...

bool	isBelow (const Directory &directory, std::size_t depthLimit=50) const
	Returns true if this filesystem entry is in a subdirectory of the given `directory` – ie, if that directory is a parent or grandparent of this filepath. More...

bool	isAbsolutePath () const noexcept
	Returns true if the path this object holds is an absolute path. More...

bool	isRelativePath () const noexcept
	Returns true if the path this object holds is a relative path. More...

bool	isValid () const noexcept
	Returns true if this object holds a valid filesystem path. More...

bool	isHidden () const
	Returns true if this path is a hidden file or directory. More...

FilesystemEntry	getSibling (const std::string_view &siblingName) const
	Returns a filesystem entry with the given name in the same directory as this one. More...

bool	exists () const noexcept
	Returns true if the filesystem object this object refers to exists on disk. More...

	operator bool () const noexcept
	Returns true if this filesystem object exists. More...

virtual std::uintmax_t	sizeInBytes () const
	Returns the size, in bytes, of the filesystem entry referred to by this object. More...

Time	getLastModificationTime () const noexcept
	Returns the last modification time of the filesystem entry. More...

std::optional< Volume >	getVolume () const noexcept
	Returns a Volume object representing the logical filesystem volume that this object exists on. More...

std::optional< File >	getFileObject () const noexcept
	If this object refers to a file, constructs a File object referring to the same file. More...

std::optional< Directory >	getDirectoryObject () const noexcept
	If this object refers to a directory, constructs a Directory object referring to the same directory. More...

std::optional< SymLink >	getSymLinkObject () const noexcept
	If this object refers to a symbolic link, constructs a SymLink object referring to the same link. More...

virtual bool	createIfDoesntExist () const noexcept
	Creates the filesystem entry this object refers to, if it doesn't already exist. More...

bool	deleteIfExists () const noexcept
	Deletes the filesystem entry this object refers to, if it exists. More...

bool	moveToTrash () noexcept
	Attempts to move this filesystem object to the system's trash folder. More...

void	touch () const
	If the filesystem entry this object refers do doesn't exist, this function creates it. More...

bool	touch_noCreate () const
	The same as `touch()` , except this function does not create the filesystem entry if it didn't already exist. More...

bool	rename (const Path &newPath) noexcept
	Renames this filesystem object to a new path. More...

bool	setPermissions (FSPerms permissions, PermOptions options=PermOptions::replace) const noexcept
	Sets the permissions for the filesystem entry. More...

Permissions	getPermissions () const
	Returns the current permissions of the filesystem entry this object refers to. More...

bool	copyTo (const Path &dest, CopyOptions options=CopyOptions::update_existing) const noexcept
	Creates a copy of this filesystem entry at a new location on disk. More...

bool	copyTo (const FilesystemEntry &dest, CopyOptions options=CopyOptions::update_existing) const noexcept
	Creates a copy of this filesystem entry at a new location on disk. More...

std::optional< FilesystemEntry >	copyToDirectory (const Path &destDirectory, CopyOptions options=CopyOptions::update_existing) const noexcept
	Creates a copy of this filesystem object, with the same filename, in a different directory. More...

Static Public Member Functions
Symbolic link creation
static std::optional< SymLink >	create (const Path &linkPath, const Path &target) noexcept
	Creates a symbolic link on the filesystem. More...

static std::optional< SymLink >	create (const Path &linkPath, const FilesystemEntry &target) noexcept
	Creates a symbolic link on the filesystem. More...

static std::optional< SymLink >	create (const Directory &newDirectory, const Path &target) noexcept
	Creates a symbolic link to the specified object in the new directory. More...

static std::optional< SymLink >	create (const Directory &newDirectory, const FilesystemEntry &target) noexcept
	Creates a symbolic link on the filesystem. More...

Additional Inherited Members
Public Types inherited from limes::files::FilesystemEntry
using	PermOptions = std::filesystem::perm_options
	Options bitfield for setting permissions. More...

using	CopyOptions = std::filesystem::copy_options
	Options bitfield for copying. More...

using	Time = std::filesystem::file_time_type
	A time point used for filesystem time. More...

Related Functions inherited from limes::files::FilesystemEntry
std::ostream &	operator<< (std::ostream &os, const FilesystemEntry &value)
	Writes a FilesystemEntry's path to the output stream. More...

Detailed Description

This class represents a symbolic link on the filesystem.

This class provides static methods for creating symbolic links, and can follow links recursively or non-recursively.

Definition at line 40 of file lfilesystem_SymLink.h.

Constructor & Destructor Documentation

◆ SymLink()

limes::files::SymLink::SymLink	(	const Path &	symLinkPath,
		const FilesystemEntry &	linkTarget
	)

explicit

Creates a symbolic link object (the link itself will also be created on the filesystem).

Note that this constructor will always create the link itself on the filesystem if it did not exist, and will throw an exception if creating the link fails.

For a non-throwing option for creating symbolic links, use the create() functions.

Exceptions

std::runtime_error An exception is thrown if the symbolic link could not be created correctly.

See also: create()

Member Function Documentation

◆ create() [1/4]

static std::optional<SymLink> limes::files::SymLink::create	(	const Directory &	newDirectory,
		const FilesystemEntry &	target
	)

staticnoexcept

Creates a symbolic link on the filesystem.

Parameters

linkPath	The path to the symbolic link to be created.
target	The filesystem object that the new link will reference.

Returns: A SymLink object referencing the newly created link; or std::nullopt if an error occurred.

◆ create() [2/4]

static std::optional<SymLink> limes::files::SymLink::create	(	const Directory &	newDirectory,
		const Path &	target
	)

staticnoexcept

Creates a symbolic link to the specified object in the new directory.

The created symlink will be at <newDirectory>/<origFilename> .

For example, this code creates a link at the path /target/directory/file.xml that refers to the file /my/special/file.xml :

const limes::files::Path linkTarget { "/my/special/file.xml" };
 
const limes::files::Directory targetDir { "/target/directory" };
 
limes::files::SymLink::create (targetDir, linkTarget);

Parameters

newDirectory	The new directory to create the link in.
target	The filesystem object that the new link will reference.

Returns: A SymLink object referencing the newly created link; or std::nullopt if an error occurred.

◆ create() [3/4]

static std::optional<SymLink> limes::files::SymLink::create	(	const Path &	linkPath,
		const FilesystemEntry &	target
	)

staticnoexcept

Creates a symbolic link on the filesystem.

Parameters

linkPath	The path to the symbolic link to be created.
target	The filesystem object that the new link will reference.

Returns: A SymLink object referencing the newly created link; or std::nullopt if an error occurred.

◆ create() [4/4]

static std::optional<SymLink> limes::files::SymLink::create	(	const Path &	linkPath,
		const Path &	target
	)

staticnoexcept

Creates a symbolic link on the filesystem.

Parameters

linkPath	The path to the symbolic link to be created.
target	The filesystem object that the new link will reference.

Returns: A SymLink object referencing the newly created link; or std::nullopt if an error occurred.

◆ FilesystemEntry() [1/2]

limes::files::FilesystemEntry::FilesystemEntry

default

Creates a FilesystemEntry with an empty path.

After creating a FilesystemEntry with this default constructor, calling isValid() on it will return false. You can use the assignPath() function to assign this object to a path after it has been constructed.

◆ FilesystemEntry() [2/2]

limes::files::FilesystemEntry::FilesystemEntry

explicit

Creates a FilesystemEntry referring to the specified path.

Parameters

pathToUse The path to this filesystem entry. This can be an absolute or relative path, and it is not an error if the passed path doesn't actually exist on disk. The path will be normalized using the normalizePath() function.

◆ follow()

FilesystemEntry limes::files::SymLink::follow ( std::size_t recursionDepth = 50 ) const

noexcept

Follows the symbolic link to find its target.

Parameters

recursionDepth Controls how many successive symlinks will be followed. If this is 0, the first direct target of this symlink will be returned, even if it is itself a symlink.

Todo:: protection from cycles? The recursion depth helps, but we could throw an exception if a cycle begins (one of the targets is the same as one of the previous targets). This would require storing the previously visited targets in memory, so the question becomes if this is worth it.

◆ isDangling()

bool limes::files::SymLink::isDangling ( ) const

noexcept

Returns true if this symbolic link's target does not exist.

◆ isDirectory()

bool limes::files::SymLink::isDirectory ( ) const

finalvirtualnoexcept

Returns true if this filesystem entry refers to a directory.

See also: isFile(), isSymLink()

Reimplemented from limes::files::FilesystemEntry.

◆ isFile()

bool limes::files::SymLink::isFile ( ) const

finalvirtualnoexcept

Returns true if this filesystem entry refers to a file.

If this path is not an existing directory or symlink, this class will assume that the path refers to a nonexistent file, because a file is assumed to be the "default" type of filesystem object.

See also: isDirectory(), isSymLink()

Reimplemented from limes::files::FilesystemEntry.

◆ isSymLink()

bool limes::files::SymLink::isSymLink ( ) const

finalvirtualnoexcept

Returns true if this filesystem entry refers to a symbolic link.

See also: isFile(), isDirectory()

Reimplemented from limes::files::FilesystemEntry.

◆ references()

bool limes::files::SymLink::references	(	const FilesystemEntry &	entry,
		std::size_t	recursionDepth = `50`
	)		const

noexcept

Returns true if this symbolic link references the given FilesystemEntry, either as its immediate target or as part of the chain of recursive symbolic links (if one exists).

Parameters

recursionDepth Controls how many successive symlinks will be followed. If this is 0, only the first direct target of this symlink will be checked, even if it is itself a symlink.

◆ referencesSameLocationAs()

bool limes::files::SymLink::referencesSameLocationAs ( const SymLink & other ) const

Returns true if the other symbolic link references the same target as this one, either as its immediate target or as part of the chain of recursive symbolic links (if one exists).

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

lfilesystem_SymLink.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SymLink()

Member Function Documentation

◆ create() [1/4]

◆ create() [2/4]

◆ create() [3/4]

◆ create() [4/4]

◆ FilesystemEntry() [1/2]

◆ FilesystemEntry() [2/2]

◆ follow()

◆ isDangling()

◆ isDirectory()

◆ isFile()

◆ isSymLink()

◆ references()

◆ referencesSameLocationAs()