mirror of
https://github.com/facebook/sapling.git
synced 2024-10-10 16:57:49 +03:00
0d5145389d
Summary: this is largely just markdownified comments from `eden/fs/utils/PathFuncs.h`. I've been a bit confused on the differences lately and how they interact, so I read through that file and thought a markdown file would be helpful for future reference, since the file is reaching 2000 lines. Reviewed By: fanzeyi Differential Revision: D19434132 fbshipit-source-id: 0ec5551e9da0a3202fcc3efff52f9f6f48f99db4
5.1 KiB
5.1 KiB
Paths within EdenFS
Path Types
There are three Path
object types, each with a stored and non-stored (Piece
)
variation. PathComponent
and RelativePath
were introduced to have the type
system prevent accidental bugs with using the wrong types in the wrong places.
Their purpose was originally to deal with names in our inode namespace.
AbsolutePath
was introduced later with the intent to track names in the system
VFS namespace rather than in our mount point namespace.
Values of each of the following types are immutable. They are internally stored
as either a std::string
or a folly::StringPiece
, depending on if the Path
is stored or non-stored (Piece
).
PathComponent
/PathComponentPiece
- Represents a name within a directory
- Illegal to
- Contain directory separator ("/")
- Be empty
- Be a relative component (".." or "..")
RelativePath
/RelativePathPiece
- Represents any number of
PathComponent(Piece)
s strung together - Illegal to begin with or be composed with an
AbsolutePath(Piece)
- Allowed to be empty
AbsolutePath
/AbsolutePathPiece
- Must begin with a "/"
- May be composed with
PathComponent
s andRelativePath
s - May not be composed with other
AbsolutePath
s
Construction
- Paths can be constructed from the following types:
folly::StringPiece
- Stored path
- Non-stored path
- Default constructed to an empty value
- Paths can be move-constructed from
std::string
values and Stored values.
Comparisons
- Comparisons can be made between Stored and Piece variations of the same type,
meaning one can compare a
RelativePath
to aRelativePathPiece
, but cannot compare aRelativePath
to anAbsolutePath
.
Iterator
ComposedPathIterator
- Used for iteration of aRelativePath
/AbsolutePath
using various iteration methods (paths()
,allPaths()
,suffixes()
,findParents()
). An iterator over prefixes of a composed path. Iterating yields a series of composed path elements. For example, iterating the path "foo/bar/baz" will yield this series of Piece elements:- "/" but only for
AbsolutePath
- "foo"
- "foo/bar"
- "foo/bar/baz"
- "/" but only for
- Note: You may use the
dirname()
andbasename()
methods to focus on the portions of interest. PathComponentIterator
- Used for iteration of a ComposedPath using the iteration methodcomponents()
. An iterator over components of a composed path. Iterating yields a series of independent path elements. For example, iterating the relative path "foo/bar/baz" will yield this series of PathComponentPiece elements:- "foo"
- "bar"
- "baz"
- Note: Iterating the absolute path "/foo/bar/baz" would also yield the same sequence.
Utility Functions
stringPiece()
- Returns the path as afolly::StringPiece
copy()
- Returns a stored (deep) copy of this pathpiece()
- Returns a non-stored (shallow) copy of this pathvalue()
- Returns a reference to the underlying stored valuebasename()
- Given a path like "a/b/c", returns "c"dirname()
- Given a path like "a/b/c", returns "a/b"getcwd()
- Gets the current working directory as anAbsolutePath
canonicalPath()
- Removes duplicate "/" characters, resolves "/./" and "/../" components. "//foo" is converted to "/foo". Does not resolve symlinks. If the path is relative, the current working directory is prepended to it. This succeeds even if the input path does not existjoinAndNormalize()
- canonicalize a path string relative to a relative path baserelpath()
- Converts an arbitrary unsanitized input string to a normalizedAbsolutePath
. This resolves symlinks, as well as "." and "." components in the input path. If the input path is a relative path, it is converted to an absolute path. This throws if the input path does not exist or if a parent directory is inaccessibleexpandUser()
- Returns a new path with~
replaced by the path to the current user's home directory. This function does not support expanding the home dir of arbitrary users, and will throw an exception if the string starts with~
but not~/
. The resulting path will be passed throughcanonicalPath()
and returnednormalizeBestEffort()
- Attempts to normalize a path by first attemptingrelpath()
and falling back tocanonicalPath()
on failure.splitFirst()
- Splits a path into the first component and the remainder of the path. If the path has only one component, the remainder will be empty. If the path is empty, an exception is thrownensureDirectoryExists()
- Ensures that the specified path exists as a directory. This creates the specified directory if necessary, creating any parent directories as required as well. Returns true if the directory was created, and false if it already existed. Throws an exception on error, including if the path or one of its parent directories is a file rather than a directoryremoveRecursively()
- Recursively removes a directory tree. Returns false if the directory did not exist in the first place, and true if the directory was successfully removed. Throws an exception on error.