Update docs of Path module according to new naming

Author: harendra-kumar

core/src/Streamly/FileSystem/Path.hs

@@ -5,92 +5,94 @@
 -- Maintainer  : [email protected]
 -- Portability : GHC
 --
--- Well typed, flexible, extensible and efficient file systems paths,
--- preserving the OS and filesystem encoding.
+-- File system paths with flexible (gradual) typing, extensible,
+-- high-performance, preserving the OS and filesystem encoding.
 --
 -- /Flexible/: you can choose the level of type safety you want. 'Path' is the
 -- basic path type which can represent a file, directory, absolute or relative
 -- path with no restrictions. Depending on how much type safety you want, you
 -- can choose appropriate type wrappers or a combination of those to wrap the
 -- 'Path' type.
 --
--- = Rooted Paths vs Path Segments
+-- = Rooted Paths vs Branches
 --
 -- For the safety of the path append operation we make the distinction of
--- rooted paths vs path segments. A path that starts from some implicit or
+-- rooted paths vs branches. A path that starts from some implicit or
 -- explicit root in the file system is a rooted path, for example, @\/usr\/bin@
 -- is a rooted path starting from an explicit file system root directory @/@.
 -- Similarly, @.\/bin@ is a path with an implicit root, this path is hanging
--- from the current directory. A path that is not rooted is called a path
--- segment e.g. @local\/bin@ is a segment.
+-- from the current directory. A path that is not rooted is called a branch
+-- e.g. @local\/bin@ is a branch.
 --
 -- This distinction affords safety to the path append operation. We can always
--- append a segment to a rooted path or to another segment. However, it does
+-- append a branch to a rooted path or to another branch. However, it does
 -- not make sense to append a rooted path to another rooted path. The default
 -- append operation in the Path module checks for this and fails if the
 -- operation is incorrect. However, the programmer can force it by using the
--- unsafe version of append operation. You can also drop the root explicitly
--- and use the safe append operation.
+-- unsafe version of the append operation. You can also drop the root
+-- explicitly and use the safe append operation.
 --
--- The "Streamly.FileSystem.Path.LocSeg" module provides explicit typing of
--- rooted paths vs path segments. Rooted paths are represented by the @Loc
--- Path@ type and path segments are represented by the @Seg Path@ type. If you
--- use the 'Path' type then append can fail if you try to append a rooted
--- location to another path, but if you use @Loc Path@ or @Seg Path@ types then
--- append can never fail at run time as the types would not allow it at compile
--- time.
+-- The "Streamly.FileSystem.Path.Seg" module provides explicit typing of path
+-- segments e.g. rooted paths vs branches. Rooted paths are represented by the
+-- @Rooted Path@ type and branches are represented by the @Branch Path@ type.
+-- If you use the 'Path' type then append can fail if you try to append a
+-- rooted path to another path, but if you use @Rooted Path@ and @Branch Path@
+-- types then append can never fail at run time as the types would not allow it
+-- at compile time.
 --
 -- = Absolute vs Relative Rooted Paths
 --
 -- Rooted paths can be absolute or relative. Absolute paths have an absolute
 -- root e.g. @\/usr\/bin@. Relative paths have a dynamic or relative root e.g.
 -- @.\/local\/bin@, or @.@, in these cases the root is current directory which
 -- is not absolute but can change dynamically. Note that there is no type level
--- distinction for absolute and relative paths.
+-- distinction for absolute and relative paths. The append operation requires a
+-- distinction between Rooted and Branch only.
 --
 -- = File vs Directory Paths
 --
--- Independently of the rooted or segment distinction you can also make the
--- distinction between files and directories using the
--- "Streamly.FileSystem.Path.FileDir" module. @File Path@ type represents a
--- file whereas @Dir Path@ represents a directory. It provides safety against
--- appending a path to a file. Append operation does not allow appending to
--- 'File' types.
+-- Independent of the rooted or branch distinction you can also make a type
+-- level distinction between file and directory type nodes using the
+-- "Streamly.FileSystem.Path.Node" module. @File Path@ type represents a file
+-- whereas @Dir Path@ represents a directory. This distinction provides safety
+-- against appending a path to a file. Append operation does not allow
+-- appending to 'File' types.
 --
 -- By default a path with a trailing separator is implicitly considered a
 -- directory path. However, the absence of a trailing separator does not convey
 -- any information, it could either be a directory or a file. Thus the append
--- operation allows appending to even the paths that do not have a trailing
+-- operation allows appending to even paths that do not have a trailing
 -- separator. However, when creating a typed path of 'File' type the conversion
 -- fails unless we explicitly drop the trailing separator.
 --
 -- = Flexible Typing
 --
--- You can use the 'Loc', 'Seg' or 'Dir', 'File' types independent of each
--- other by using only the required module. If you want both types of
+-- You can use the 'Rooted', 'Branch' or 'Dir', 'File' types independent of
+-- each other by using only the required module. If you want both types of
 -- distinctions then you can use them together as well using the
--- "Streamly.FileSystem.Path.Typed" module.  For example, the @Loc (Dir Path)@
--- represents a rooted path which is a directory. You can only append to a path
--- that has 'Dir' in it and you can only append a 'Seg' type.
+-- "Streamly.FileSystem.Path.SegNode" module.  For example, the @Rooted (Dir
+-- Path)@ represents a rooted path which is a directory. You can only append to
+-- a path that has 'Dir' in it and you can only append a 'Branch' type.
 --
 -- You can choose to use just the basic 'Path' type or any combination of safer
--- types. You can upgrade or downgrade the safety using the @adapt@ operation.
--- Whenever a less restrictive path type is converted to a more restrictive
--- path type, the conversion involves run-time checks and it may fail. However,
--- a more restrictive path type can be freely converted to a less restrictive
--- one.
+-- types. You can upgrade or downgrade the safety by converting types using the
+-- @adapt@ operation. Whenever a less restrictive path type is converted to a
+-- more restrictive path type, the conversion involves run-time checks and it
+-- may fail. However, a more restrictive path type can be freely converted to a
+-- less restrictive one.
 --
 -- = Extensibility
 --
--- Extensible, you can define your own newtype wrappers similar to 'File' or
--- 'Dir' to provide custom restrictions if you want.
+-- You can define your own newtype wrappers similar to 'File' or 'Dir' to
+-- provide custom restrictions if you want.
 --
 -- = Compatibility
 --
 -- Any path type can be converted to the 'FilePath' type using the 'toString'
 -- operation. Operations to convert to and from 'OsPath' type at zero cost are
 -- provided in the @streamly-filepath@ package. This is possible because the
--- types use the same underlying representation as the 'OsPath' type.
+-- types use an underlying representation which is compatible with the 'OsPath'
+-- type.
 --
 -- = String Creation Quasiquoter
 --

core/src/Streamly/Internal/FileSystem/Path.hs

@@ -24,31 +24,31 @@
 -- in the presence of symlinks it could be a DAG or a graph, because directory
 -- symlinks can create cycles.
 --
--- == Location and Segments
+-- == Rooted and Branch paths
 --
--- We make two distinctions for paths, a path could refer to a location or it
--- could refer to a segment or segments.
+-- We make two distinctions for paths, a path may a specific filesystem root
+-- attached to it or it may be a free branch without a root attached.
 --
--- A path that refers to a particular object in the file system  is called a
--- location e.g. /usr is a location, . is a location, ./bin is a location. A
--- location could be absolute e.g. /usr or it could be relative e.g. ./bin . A
--- location always has two components, a specific "root" which could be
--- explicit or implicit, and a path segment relative to the root. A location
--- with a fixed root is known as an absolute location whereas a location with
--- an implicit root e.g. "./bin" is known as a relative location.
+-- A path that has a root attached to it is called a rooted path e.g. /usr is a
+-- rooted path, . is a rooted path, ./bin is a rooted path. A rooted path could
+-- be absolute e.g. /usr or it could be relative e.g. ./bin . A rooted path
+-- always has two components, a specific "root" which could be explicit or
+-- implicit, and a path segment relative to the root. A rooted path with a
+-- fixed root is known as an absolute path whereas a rooted path with an
+-- implicit root e.g. "./bin" is known as a relative path.
 --
--- A path that does not refer to a particular location but defines steps to go
--- from some place to another is a path segment. For example, "local/bin" is a
--- path segment whereas "./local/bin" is a location.
+-- A path that does not have a root attached but defines steps to go from some
+-- place to another is a path branch. For example, "local/bin" is a path branch
+-- whereas "./local/bin" is a rooted path.
 --
--- Locations can never be appended to another location or to a path segment
--- whereas a segment can be appended.
+-- Rooted paths can never be appended to any other path whereas a branch can be
+-- appended.
 --
 -- == Comparing Paths
 --
--- We can compare two absolute locations or path segments but we cannot compare
--- two relative locations. If each component of the path is the same then the
--- paths are considered to be equal.
+-- We can compare two absolute rooted paths or path branches but we cannot
+-- compare two relative rooted paths. If each component of the path is the same
+-- then the paths are considered to be equal.
 --
 -- == Implicit Roots (.)
 --
@@ -68,16 +68,16 @@
 -- We can treat @.\/bin\/ls@ as an absolute path with "." as an implicit root.
 -- The relative path is "bin/ls" which represents steps from somewhere to
 -- somewhere else rather than a particular location. We can also call @./bin@
--- as a "located path" as it points to particular location rather than "steps"
--- from one place to another. If we want to append such paths we need to first
--- make them explicitly relative by dropping the implicit root. Or we can use
--- unsafeAppend to force it anyway or unsafeCast to convert absolute to
--- relative.
+-- as a "rooted path" as it starts from particular location rather than
+-- defining "steps" to go from one place to another. If we want to append such
+-- paths we need to first make them explicitly relative by dropping the
+-- implicit root. Or we can use unsafeAppend to force it anyway or unsafeCast
+-- to convert absolute to relative.
 --
--- On these absolute (located/Loc) paths if we use takeRoot, it should return
+-- On these absolute (Rooted) paths if we use takeRoot, it should return
 -- RootCurDir, RootCurDrive and @Root Path@ to distinguish @./@, @/@, @C:/@. We
--- could represent them by different types but that would make the types even more
--- complicated. So runtime checks are are a good balance.
+-- could represent them by different types but that would make the types even
+-- more complicated. So runtime checks are are a good balance.
 --
 -- Path comparison should return EqTrue, EqFalse or EqUnknown. If we compare
 -- these absolute/located paths having implicit roots then result should be

core/src/Streamly/Internal/FileSystem/PosixPath.hs

@@ -366,8 +366,12 @@ unsafeAppend (OS_PATH a) (OS_PATH b) =
         $ Common.unsafeAppend
             Common.OS_NAME (Common.toString Unicode.UNICODE_DECODER) a b
 
--- | Append a OS_PATH to another. Fails if the second path refers to a location
--- and not a path segment.
+-- XXX Should we fail if the first path does not have a trailing separator i.e.
+-- it is not a directory?
+
+-- | Append a OS_PATH to another. Fails if the second path refers to a rooted
+-- path and not a branch. Use 'unsafeAppend' to avoid failure if you know it is
+-- ok to append the path.
 --
 -- >>> Path.toString $ Path.append [path|/usr|] [path|bin|]
 -- "/usr/bin"

core/src/Streamly/Internal/FileSystem/PosixPath/SegNode.hs

@@ -220,15 +220,15 @@ rtdir = mkQ rtdirE
 brdir :: QuasiQuoter
 brdir = mkQ brdirE
 
--- | Generates an @Rooted (File OS_PATH)@ type from a quoted literal.
+-- | Generates a @Rooted (File OS_PATH)@ type from a quoted literal.
 --
--- >>> Path.toString ([rtfile|/usr|] :: Rooted (File PosixPath))
--- "/usr"
+-- >>> Path.toString ([rtfile|/x.txt|] :: Rooted (File PosixPath))
+-- "/x.txt"
 --
 rtfile :: QuasiQuoter
 rtfile = mkQ rtfileE
 
--- | Generates an @Branch (File OS_PATH)@ type from a quoted literal.
+-- | Generates a @Branch (File OS_PATH)@ type from a quoted literal.
 --
 -- >>> Path.toString ([brfile|x.txt|] :: Branch (File PosixPath))
 -- "x.txt"

core/streamly-core.cabal

@@ -37,8 +37,8 @@ description:
   This package covers some or all of the functionality covered
   by @streaming, pipes, conduit, list-t, logic-t, foldl, attoparsec,
   array, primitive, vector, vector-algorithms, binary, cereal, store,
-  bytestring, text, stringsearch, interpolate@. Streamly provides a
-  consistent, concise, modular and performant interface for all this
+  bytestring, text, stringsearch, interpolate, filepath, path@. Streamly
+  provides a consistent, concise, modular and performant interface for all this
   functionality.
   .
   Note: The dependencies "heaps" and "monad-control" are included in