Rename isBranch to isUnrooted

harendra-kumar · harendra-kumar · commit 661a310cc0d6 · 2025-07-15T15:42:46.000+05:30
diff --git a/core/src/Streamly/FileSystem/Path.hs b/core/src/Streamly/FileSystem/Path.hs
@@ -22,31 +22,29 @@
 -- of the @filepath@ package, some differences exist due to a slightly
 -- different design philosophy focused on better safety.
 --
--- = Rooted Paths vs Branches
+-- = Rooted vs Unrooted Paths
 --
 -- To ensure the safety of the path append operation, we distinguish between
--- rooted paths and branch-type paths. A path that starts from an explicit or
--- implicit file system root is called a rooted path or an anchored path. For
--- example, @\/usr\/bin@ is a rooted path with an explicit root directory @/@.
--- Similarly, @.\/bin@ is a rooted path with an implicit root, anchored at the
--- current directory. A path that is not rooted is called a branch type path or
--- unanchored path; for example, @local\/bin@ is a branch.
+-- rooted paths and free path segments or unrooted paths. A path that starts
+-- from an explicit or implicit file system root is called a rooted path or an
+-- anchored path. For example, @\/usr\/bin@ is a rooted path with @/@ as an
+-- explicit root directory. Similarly, @.\/bin@ is a rooted path with the
+-- current directoy \".\" as an implicit root. A path that is not rooted is
+-- called an unrooted path or unanchored path; for example, @local\/bin@ is an
+-- unrooted path.
 --
 -- This distinction ensures the safety of the path append operation. You can
--- append only a branch type path to another path, it does not make sense to
+-- append only an unrooted path to another path, it does not make sense to
 -- append a rooted path to another path. The default append operation in the
--- Path module checks for this and fails if the operation is invalid. However,
--- the programmer can force the unsafe behavior by using the unsafe append
--- operation. Alternatively, you can drop the root explicitly and use the safe
--- append.
---
--- Rooted vs branch distinction is a stricter form of relative vs absolute path
--- distinction. Essentially, paths relative to the current directory are also
--- treated in the same way as absolute paths, from the perspective of an append
--- operation. The meaning of current directory is context dependent and
--- dynamic, therefore, appending it to another path is not allowed. Only pure
--- branch-type paths (e.g. @local/bin@) can be appended to any other path using
--- safe operations.
+-- Path module checks for this and fails if the operation is invalid.
+--
+-- Rooted vs unrooted distinction is a stricter form of relative vs absolute
+-- path distinction. In this model, for better safety, paths relative to the
+-- current directory are also treated in the same way as absolute paths, from
+-- the perspective of a path append operation. This is because the  meaning of
+-- current directory is context dependent and dynamic, therefore, appending it
+-- to another path is not allowed. Only unrooted path segments (e.g.
+-- @local/bin@) can be appended to any other path using safe operations.
 --
 -- = File vs. Directory Paths
 --
@@ -102,7 +100,7 @@ module Streamly.FileSystem.Path
 
     -- * Path Info
     , isRooted
-    , isBranch
+    , isUnrooted
 
     -- * Joining
     , unsafeExtend
diff --git a/core/src/Streamly/FileSystem/Path/Seg.hs b/core/src/Streamly/FileSystem/Path/Seg.hs
@@ -5,7 +5,7 @@
 -- Maintainer  : streamly@composewell.com
 -- Portability : GHC
 --
--- Represent 'Rooted' or 'Branch' type path segments explicitly as separate
+-- Represent 'Rooted' or 'Unrooted' type path segments explicitly as separate
 -- types for the safety of path append operation. A Rooted path is an absolute
 -- path or a path that is relative to the current directory with a leading dot.
 -- Rooted paths cannot be appended to other paths.
@@ -16,18 +16,18 @@ module Streamly.FileSystem.Path.Seg
     (
     -- * Types
       Rooted
-    , Branch
+    , Unrooted
     , IsSeg
 
     -- * Statically Verified Path Literals
     -- | Quasiquoters.
     , rt
-    , br
+    , ur
 
     -- * Statically Verified Path Strings
     -- | Template Haskell expression splices.
     , rtE
-    , brE
+    , urE
 
     -- * Operations
     , extend
diff --git a/core/src/Streamly/FileSystem/Path/SegNode.hs b/core/src/Streamly/FileSystem/Path/SegNode.hs
@@ -5,7 +5,7 @@
 -- Maintainer  : streamly@composewell.com
 -- Portability : GHC
 --
--- Use 'Rooted' or 'Branch' path segment type annotations as well as 'File' and
+-- Use 'Rooted' or 'Unrooted' path segment type annotations as well as 'File' and
 -- 'Dir' node type annotations on the same path for the safety of path append
 -- operation. A Rooted path cannot be appended to other paths, and you canno
 -- append a path to a 'File' type path.
@@ -18,16 +18,16 @@ module Streamly.FileSystem.Path.SegNode
     -- * Statically Verified Path Literals
     -- | Quasiquoters.
       rtdir
-    , brdir
+    , urdir
     , rtfile
-    , brfile
+    , urfile
 
     -- * Statically Verified Path Strings
     -- | Template Haskell expression splices.
     , rtdirE
-    , brdirE
+    , urdirE
     , rtfileE
-    , brfileE
+    , urfileE
 
     -- * Operations
     , extend
diff --git a/core/src/Streamly/Internal/FileSystem/PosixPath.hs b/core/src/Streamly/Internal/FileSystem/PosixPath.hs
@@ -156,7 +156,7 @@ module Streamly.Internal.FileSystem.OS_PATH_TYPE
 
     -- * Path Segment Types
     , isRooted
-    , isBranch
+    , isUnrooted
 
     -- * Joining
     , extendByString
@@ -873,21 +873,21 @@ isRooted (OS_PATH arr) = Common.isRooted Common.OS_NAME arr
 
 -- | A path that is not attached to a root e.g. @a\/b\/c@ or @..\/b\/c@.
 --
--- >>> isBranch = not . Path.isRooted
+-- >>> isUnrooted = not . Path.isRooted
 --
--- >>> isBranch = Path.isBranch . Path.fromString_
+-- >>> isUnrooted = Path.isUnrooted . Path.fromString_
 --
--- >>> isBranch "x"
+-- >>> isUnrooted "x"
 -- True
--- >>> isBranch "x/y"
+-- >>> isUnrooted "x/y"
 -- True
--- >>> isBranch ".."
+-- >>> isUnrooted ".."
 -- True
--- >>> isBranch "../x"
+-- >>> isUnrooted "../x"
 -- True
 --
-isBranch :: OS_PATH_TYPE -> Bool
-isBranch = not . isRooted
+isUnrooted :: OS_PATH_TYPE -> Bool
+isUnrooted = not . isRooted
 
 #ifndef IS_WINDOWS
 -- | Like 'extend' but does not check if the second path is rooted.
diff --git a/core/src/Streamly/Internal/FileSystem/PosixPath/Seg.hs b/core/src/Streamly/Internal/FileSystem/PosixPath/Seg.hs
@@ -19,10 +19,10 @@
 --
 -- This module provides a type safe path append operation by distinguishing
 -- paths between rooted paths and branches. Rooted paths are represented by the
--- @Rooted OS_PATH@ type and branches are represented by the @Branch OS_PATH@
+-- @Rooted OS_PATH@ type and branches are represented by the @Unrooted OS_PATH@
 -- type. Rooted paths are paths that are attached to specific roots in the file
 -- system. Rooted paths could be absolute or relative e.g. @\/usr\/bin@,
--- @.\/local\/bin@, or @.@. Branches are a paths that are not attached to a
+-- @.\/local\/bin@, or @.@. Unrootedes are a paths that are not attached to a
 -- specific root e.g. @usr\/bin@, @local\/bin@, or @../bin@ are branches.
 --
 -- This distinction provides a safe path append operation which cannot fail.
@@ -33,18 +33,18 @@ module Streamly.Internal.FileSystem.OS_PATH.Seg
     (
     -- * Types
       Rooted (..)
-    , Branch (..)
+    , Unrooted (..)
     , IsSeg
 
     -- * Statically Verified Path Literals
     -- | Quasiquoters.
     , rt
-    , br
+    , ur
 
     -- * Statically Verified Path Strings
     -- | Template Haskell expression splices.
     , rtE
-    , brE
+    , urE
 
     -- * Operations
     , extend
@@ -68,13 +68,13 @@ import qualified Streamly.Internal.FileSystem.OS_PATH as OsPath
 For APIs that have not been released yet.
 
 >>> import Streamly.Internal.FileSystem.PosixPath (PosixPath)
->>> import Streamly.Internal.FileSystem.PosixPath.Seg (Rooted, Branch, rt, br)
+>>> import Streamly.Internal.FileSystem.PosixPath.Seg (Rooted, Unrooted, rt, ur)
 >>> import qualified Streamly.Internal.FileSystem.PosixPath as Path
 >>> import qualified Streamly.Internal.FileSystem.PosixPath.Seg as Seg
 -}
 
 newtype Rooted a = Rooted a
-newtype Branch a = Branch a
+newtype Unrooted a = Unrooted a
 
 instance IsPath OS_PATH (Rooted OS_PATH) where
     unsafeFromPath = Rooted
@@ -87,22 +87,22 @@ instance IsPath OS_PATH (Rooted OS_PATH) where
                 ++ OsPath.toString p
     toPath (Rooted p) = p
 
-instance IsPath OS_PATH (Branch OS_PATH) where
-    unsafeFromPath = Branch
+instance IsPath OS_PATH (Unrooted OS_PATH) where
+    unsafeFromPath = Unrooted
     fromPath p =
-        if OsPath.isBranch p
-        then pure (Branch p)
+        if OsPath.isUnrooted p
+        then pure (Unrooted p)
         -- XXX Add more detailed error msg with all valid examples.
         else throwM $ InvalidPath
                 $ "Must be a path segment, not a specific location: "
                 ++ OsPath.toString p
-    toPath (Branch p) = p
+    toPath (Unrooted p) = p
 
--- | Constraint to check if a type has Rooted or Branch annotations.
+-- | Constraint to check if a type has Rooted or Unrooted annotations.
 class IsSeg a
 
 instance IsSeg (Rooted a)
-instance IsSeg (Branch a)
+instance IsSeg (Unrooted a)
 
 ------------------------------------------------------------------------------
 -- Statically Verified Strings
@@ -112,19 +112,19 @@ liftRooted :: Rooted OS_PATH -> Q Exp
 liftRooted (Rooted p) =
     [| OsPath.unsafeFromString $(lift $ OsPath.toString p) :: Rooted OS_PATH |]
 
-liftBranch :: Branch OS_PATH -> Q Exp
-liftBranch (Branch p) =
-    [| OsPath.unsafeFromString $(lift $ OsPath.toString p) :: Branch OS_PATH |]
+lifUntooted :: Unrooted OS_PATH -> Q Exp
+lifUntooted (Unrooted p) =
+    [| OsPath.unsafeFromString $(lift $ OsPath.toString p) :: Unrooted OS_PATH |]
 
 -- | Generates a Haskell expression of type @Rooted OS_PATH@.
 --
 rtE :: String -> Q Exp
 rtE = either (error . show) liftRooted . OsPath.fromString
 
--- | Generates a Haskell expression of type @Branch OS_PATH@.
+-- | Generates a Haskell expression of type @Unrooted OS_PATH@.
 --
-brE :: String -> Q Exp
-brE = either (error . show) liftBranch . OsPath.fromString
+urE :: String -> Q Exp
+urE = either (error . show) lifUntooted . OsPath.fromString
 
 ------------------------------------------------------------------------------
 -- Statically Verified Literals
@@ -143,29 +143,29 @@ brE = either (error . show) liftBranch . OsPath.fromString
 rt :: QuasiQuoter
 rt = mkQ rtE
 
--- | Generates a @Branch Path@ type from a quoted literal.
+-- | Generates a @Unrooted Path@ type from a quoted literal.
 --
--- >>> Path.toString ([br|usr|] :: Branch PosixPath)
+-- >>> Path.toString ([ur|usr|] :: Unrooted PosixPath)
 -- "usr"
 --
-br :: QuasiQuoter
-br = mkQ brE
+ur :: QuasiQuoter
+ur = mkQ urE
 
 -- The only safety we need for paths is: (1) The first path can only be a Dir
--- type path, and (2) second path can only be a Branch path.
+-- type path, and (2) second path can only be a Unrooted path.
 
--- | Append a 'Branch' type path to a 'Rooted' path or 'Branch' path.
+-- | Append a 'Unrooted' type path to a 'Rooted' path or 'Unrooted' path.
 --
--- >>> Path.toString (Seg.extend [rt|/usr|] [br|bin|] :: Rooted PosixPath)
+-- >>> Path.toString (Seg.extend [rt|/usr|] [ur|bin|] :: Rooted PosixPath)
 -- "/usr/bin"
--- >>> Path.toString (Seg.extend [br|usr|] [br|bin|] :: Branch PosixPath)
+-- >>> Path.toString (Seg.extend [ur|usr|] [ur|bin|] :: Unrooted PosixPath)
 -- "usr/bin"
 --
 {-# INLINE extend #-}
 extend ::
     (
       IsSeg (a OS_PATH)
     , IsPath OS_PATH (a OS_PATH)
-    ) => a OS_PATH -> Branch OS_PATH -> a OS_PATH
-extend a (Branch c) =
+    ) => a OS_PATH -> Unrooted OS_PATH -> a OS_PATH
+extend a (Unrooted c) =
     unsafeFromPath $ OsPath.unsafeExtend (toPath a) (toPath c)
diff --git a/core/src/Streamly/Internal/FileSystem/PosixPath/SegNode.hs b/core/src/Streamly/Internal/FileSystem/PosixPath/SegNode.hs
