ScummVM
Common::FSNode Class Reference

FSNode, short for "File System Node", provides an abstraction for file paths, allowing for portable file system browsing. More...

#include <fs.h>

Inheritance diagram for Common::FSNode:
Collaboration diagram for Common::FSNode:

Public Types

enum  ListMode { kListFilesOnly = 1, kListDirectoriesOnly = 2, kListAll = 3 }
 Flag to tell listDir() which kind of files to list. More...
 

Public Member Functions

 FSNode ()
 Create a new pathless FSNode. More...
 
 FSNode (const String &path)
 Create a new FSNode referring to the specified path. More...
 
virtual ~FSNode ()
 
bool operator< (const FSNode &node) const
 Compare the name of this node to the name of another. More...
 
bool exists () const
 Indicates whether the object referred by this node exists in the filesystem or not. More...
 
FSNode getChild (const String &name) const
 Create a new node referring to a child node of the current node, which must be a directory node (otherwise an invalid node is returned). More...
 
bool getChildren (FSList &fslist, ListMode mode=kListDirectoriesOnly, bool hidden=true) const
 Return a list of all child nodes of this directory node. More...
 
virtual String getDisplayName () const
 Return a human readable string for this node, usable for display (e.g. More...
 
virtual String getName () const
 Return a string representation of the name of the file. More...
 
String getPath () const
 Return a string representation of the file which is suitable for archiving (i.e. More...
 
FSNode getParent () const
 Get the parent node of this node. More...
 
bool isDirectory () const
 Indicates whether the node refers to a directory or not. More...
 
bool isReadable () const
 Indicates whether the object referred by this node can be read from or not. More...
 
bool isWritable () const
 Indicates whether the object referred by this node can be written to or not. More...
 
virtual SeekableReadStreamcreateReadStream () const
 Creates a SeekableReadStream instance corresponding to the file referred by this node. More...
 
WriteStreamcreateWriteStream () const
 Creates a WriteStream instance corresponding to the file referred by this node. More...
 
bool createDirectory () const
 Creates a directory referred by this node. More...
 
- Public Member Functions inherited from Common::ArchiveMember
virtual ~ArchiveMember ()
 

Private Member Functions

 FSNode (AbstractFSNode *realNode)
 Construct a FSNode from a backend's AbstractFSNode implementation. More...
 

Private Attributes

SharedPtr< AbstractFSNode_realNode
 

Friends

class ::AbstractFSNode
 

Detailed Description

FSNode, short for "File System Node", provides an abstraction for file paths, allowing for portable file system browsing.

This means for example, that multiple or single roots have to be supported (compare Unix with a single root, Windows with multiple roots C:, D:, ...).

To this end, we abstract away from paths; implementations can be based on paths (and it's left to them whether / or \ or : is the path separator :-); but it is also possible to use inodes or vrefs (MacOS 9) or anything else.

Definition at line 58 of file fs.h.

Member Enumeration Documentation

◆ ListMode

Flag to tell listDir() which kind of files to list.

Enumerator
kListFilesOnly 
kListDirectoriesOnly 
kListAll 

Definition at line 74 of file fs.h.

Constructor & Destructor Documentation

◆ FSNode() [1/3]

Common::FSNode::FSNode ( AbstractFSNode realNode)
private

Construct a FSNode from a backend's AbstractFSNode implementation.

Parameters
realNodePointer to a heap allocated instance. FSNode will take ownership of the pointer.

Definition at line 33 of file fs.cpp.

◆ FSNode() [2/3]

Common::FSNode::FSNode ( )

Create a new pathless FSNode.

Since there's no path associated with this node, path-related operations (i.e. exists(), isDirectory(), getPath()) will always return false or raise an assertion.

Definition at line 30 of file fs.cpp.

◆ FSNode() [3/3]

Common::FSNode::FSNode ( const String path)
explicit

Create a new FSNode referring to the specified path.

This is the counterpart to the path() method.

If path is empty or equals ".", then a node representing the "current directory" will be created. If that is not possible (since e.g. the operating system doesn't support the concept), some other directory is used (usually the root directory).

Definition at line 37 of file fs.cpp.

◆ ~FSNode()

virtual Common::FSNode::~FSNode ( )
inlinevirtual

Definition at line 98 of file fs.h.

Member Function Documentation

◆ createDirectory()

bool Common::FSNode::createDirectory ( ) const

Creates a directory referred by this node.

This assumes that this node refers to non-existing directory. If this is not the case, false is returned.

Returns
true if the directory was created, false otherwise.

Definition at line 155 of file fs.cpp.

◆ createReadStream()

SeekableReadStream * Common::FSNode::createReadStream ( ) const
virtual

Creates a SeekableReadStream instance corresponding to the file referred by this node.

This assumes that the node actually refers to a readable file. If this is not the case, 0 is returned.

Returns
pointer to the stream object, 0 in case of a failure

Implements Common::ArchiveMember.

Definition at line 128 of file fs.cpp.

◆ createWriteStream()

WriteStream * Common::FSNode::createWriteStream ( ) const

Creates a WriteStream instance corresponding to the file referred by this node.

This assumes that the node actually refers to a readable file. If this is not the case, 0 is returned.

Returns
pointer to the stream object, 0 in case of a failure

Definition at line 143 of file fs.cpp.

◆ exists()

bool Common::FSNode::exists ( ) const

Indicates whether the object referred by this node exists in the filesystem or not.

Returns
bool true if the node exists, false otherwise.

Definition at line 59 of file fs.cpp.

◆ getChild()

FSNode Common::FSNode::getChild ( const String name) const

Create a new node referring to a child node of the current node, which must be a directory node (otherwise an invalid node is returned).

If a child matching the name exists, a normal node for it is returned. If no child with the name exists, a node for it is still returned, but exists() will return 'false' for it. This node can however be used to create a new file using the createWriteStream() method.

Todo:
If createWriteStream() (or a hypothetical future mkdir() method) is used, this should affect what exists/isDirectory/isReadable/isWritable return for existing nodes. However, this is not the case for many existing FSNode implementations. Either fix those, or document that FSNodes can become 'stale'...
Parameters
namethe name of a child of this directory
Returns
the node referring to the child with the given name

Definition at line 63 of file fs.cpp.

◆ getChildren()

bool Common::FSNode::getChildren ( FSList fslist,
ListMode  mode = kListDirectoriesOnly,
bool  hidden = true 
) const

Return a list of all child nodes of this directory node.

If called on a node that does not represent a directory, false is returned.

Returns
true if successful, false otherwise (e.g. when the directory does not exist).

Definition at line 72 of file fs.cpp.

◆ getDisplayName()

String Common::FSNode::getDisplayName ( ) const
virtual

Return a human readable string for this node, usable for display (e.g.

in the GUI code). Do not rely on it being usable for anything else, like constructing paths!

Returns
the display name

Reimplemented from Common::ArchiveMember.

Definition at line 89 of file fs.cpp.

◆ getName()

String Common::FSNode::getName ( ) const
virtual

Return a string representation of the name of the file.

This can be used e.g. by detection code that relies on matching the name of a given file. But it is not suitable for use with fopen / File::open, nor should it be archived.

Returns
the file name

Implements Common::ArchiveMember.

Definition at line 94 of file fs.cpp.

◆ getParent()

FSNode Common::FSNode::getParent ( ) const

Get the parent node of this node.

If this node has no parent node, then it returns a duplicate of this node.

Definition at line 99 of file fs.cpp.

◆ getPath()

String Common::FSNode::getPath ( ) const

Return a string representation of the file which is suitable for archiving (i.e.

writing to the config file). This will usually be a 'path' (hence the name of the method), but can be anything that meets the above criterions. What a 'path' is differs greatly from system to system anyway.

Note
Do not assume that this string contains (back)slashes or any other kind of 'path separators'.
Returns
the 'path' represented by this filesystem node

Definition at line 111 of file fs.cpp.

◆ isDirectory()

bool Common::FSNode::isDirectory ( ) const

Indicates whether the node refers to a directory or not.

Todo:
Currently we assume that a node that is not a directory automatically is a file (ignoring things like symlinks or pipes). That might actually be OK... but we could still add an isFile method. Or even replace isDirectory by a getType() method that can return values like kDirNodeType, kFileNodeType, kInvalidNodeType.

Definition at line 116 of file fs.cpp.

◆ isReadable()

bool Common::FSNode::isReadable ( ) const

Indicates whether the object referred by this node can be read from or not.

If the node refers to a directory, readability implies being able to read and list the directory entries.

If the node refers to a file, readability implies being able to read the contents of the file.

Returns
true if the object can be read, false otherwise.

Definition at line 120 of file fs.cpp.

◆ isWritable()

bool Common::FSNode::isWritable ( ) const

Indicates whether the object referred by this node can be written to or not.

If the node refers to a directory, writability implies being able to modify the directory entry (i.e. rename the directory, remove it or write files inside of it).

If the node refers to a file, writability implies being able to write data to the file.

Returns
true if the object can be written to, false otherwise.

Definition at line 124 of file fs.cpp.

◆ operator<()

bool Common::FSNode::operator< ( const FSNode node) const

Compare the name of this node to the name of another.

Directories go before normal files.

Definition at line 49 of file fs.cpp.

Friends And Related Function Documentation

◆ ::AbstractFSNode

friend class ::AbstractFSNode
friend

Definition at line 60 of file fs.h.

Member Data Documentation

◆ _realNode

SharedPtr<AbstractFSNode> Common::FSNode::_realNode
private

Definition at line 61 of file fs.h.


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