Rename some Path APIs and fix docs, doctests of some

Author: harendra-kumar

bench-test-lib/src/BenchTestLib/DirIO.hs

@@ -61,7 +61,6 @@ import qualified Streamly.Internal.Data.Unfold as Unfold
 import qualified Streamly.Internal.FileSystem.DirIO as Dir
 import qualified Streamly.FileSystem.Path as Path
 #if !defined(mingw32_HOST_OS) && !defined(__MINGW32__)
-import qualified Streamly.Internal.FileSystem.Path as Path (toChunk)
 import qualified Streamly.Internal.FileSystem.Posix.ReadDir as Dir
 #endif
 
@@ -165,7 +164,7 @@ listDirChunkedWith
     -> [Char] -> Stream IO Word8
 listDirChunkedWith act inp = do
      Stream.unfoldEachEndBy 10 Array.reader
-        $ fmap (Array.asBytes . Path.toChunk)
+        $ fmap (Array.asBytes . Path.toArray)
         $ Stream.unfoldEach Unfold.fromList
         $ fmap (either id id)
         $ act
@@ -177,7 +176,7 @@ listDirWith
     -> [Char] -> Stream IO Word8
 listDirWith act inp = do
      Stream.unfoldEachEndBy 10 Array.reader
-        $ fmap (Array.asBytes . Path.toChunk . either id id)
+        $ fmap (Array.asBytes . Path.toArray . either id id)
         $ act
         $ Stream.fromPure (Left (fromJust $ Path.fromString inp))
 

core/src/DocTestFileSystemPath.hs

@@ -0,0 +1,20 @@
+{- $setup
+>>> :m
+>>> :set -XQuasiQuotes
+>>> import Control.Exception (SomeException, evaluate, try)
+>>> import Data.Either (Either, isLeft)
+>>> import Data.Maybe (fromJust, isJust, isNothing)
+>>> import Streamly.FileSystem.Path (Path, path)
+>>> import qualified Streamly.Data.Array as Array
+>>> import qualified Streamly.Data.Stream as Stream
+>>> import qualified Streamly.FileSystem.Path as Path
+>>> import qualified Streamly.Unicode.Stream as Unicode
+
+For APIs that have not been released yet.
+
+>>> import qualified Streamly.Internal.FileSystem.Path as Path
+
+Utilities:
+
+>>> fails x = isLeft <$> (try (evaluate x) :: IO (Either SomeException String))
+-}

core/src/DocTestFileSystemPosixPath.hs

@@ -0,0 +1,19 @@
+{- $setup
+>>> :m
+>>> :set -XQuasiQuotes
+>>> import Control.Exception (SomeException, evaluate, try)
+>>> import Data.Either (Either, isLeft)
+>>> import Data.Maybe (isNothing, isJust)
+>>> import qualified Streamly.Data.Array as Array
+>>> import qualified Streamly.Data.Stream as Stream
+>>> import qualified Streamly.Unicode.Stream as Unicode
+
+For APIs that have not been released yet.
+
+>>> import Streamly.Internal.FileSystem.PosixPath (PosixPath, path)
+>>> import qualified Streamly.Internal.FileSystem.PosixPath as Path
+
+Utilities:
+
+>>> fails x = isLeft <$> (try (evaluate x) :: IO (Either SomeException String))
+-}

core/src/DocTestFileSystemWindowsPath.hs

@@ -0,0 +1,21 @@
+{- $setup
+>>> :m
+>>> :set -XQuasiQuotes
+>>> import Control.Exception (SomeException, evaluate, try)
+>>> import Data.Either (Either, isLeft)
+>>> import Data.Maybe (fromJust, isNothing, isJust)
+>>> import Data.Word (Word16)
+>>> import Streamly.Data.Array (Array)
+>>> import qualified Streamly.Data.Array as Array
+>>> import qualified Streamly.Data.Stream as Stream
+>>> import qualified Streamly.Unicode.Stream as Unicode
+
+For APIs that have not been released yet.
+
+>>> import Streamly.Internal.FileSystem.WindowsPath (WindowsPath, path)
+>>> import qualified Streamly.Internal.FileSystem.WindowsPath as Path
+
+Utilities:
+
+>>> fails x = isLeft <$> (try (evaluate x) :: IO (Either SomeException String))
+-}

core/src/Streamly/FileSystem/Path.hs

@@ -1,3 +1,4 @@
+{-# LANGUAGE CPP #-}
 -- |
 -- Module      : Streamly.FileSystem.Path
 -- Copyright   : (c) 2023 Composewell Technologies
@@ -10,9 +11,11 @@
 --
 -- The 'Path' type is built on top of Streamly's 'Array' type, leveraging all
 -- its operations — including support for both pinned and unpinned
--- representations. It is designed for extensibility and fine-grained type
--- safety. For type-safe adaptations, see the
--- "Streamly.Internal.FileSystem.Path.*" modules.
+-- representations. The API integrates with streaming, prioritizes safety,
+-- flexibility, and performance. It supports configurable equality for
+-- cross-platform compatibility and user-defined path matching. It is designed
+-- for extensibility and fine-grained type safety as well. For type-safe
+-- adaptations, see the "Streamly.Internal.FileSystem.Path.*" modules.
 --
 -- 'Path' is interconvertible with the 'OsPath' type from the @filepath@
 -- package at zero runtime cost. While the API is mostly compatible with that
@@ -68,11 +71,19 @@
 
 module Streamly.FileSystem.Path
     (
+    -- * Setup
+    -- | To execute the code examples provided in this module in ghci, please
+    -- run the following commands first.
+    --
+    -- $setup
+
     -- * Type
       Path
+    , OsWord
 
     -- * Construction
-    , fromChunk
+    , validatePath
+    , fromArray
     , fromString
 
     -- * Statically Verified String Literals
@@ -84,20 +95,15 @@ module Streamly.FileSystem.Path
     , pathE
 
     -- * Elimination
-    , toChunk
-    , toChars
+    , toArray
+    -- , toChars -- need fromChars as well
     , toString
-    , asOsCString
+    -- , asOsCString
 
     -- * Path Info
     , isRooted
     , isBranch
 
-    -- * Separators
-    , dropTrailingSeparators
-    , hasTrailingSeparator
-    , addTrailingSeparator
-
     -- * Joining
     , unsafeExtend
     , extend
@@ -123,14 +129,11 @@ module Streamly.FileSystem.Path
 
     -- * Equality
     , EqCfg
-    , eqPath
-
-#ifndef IS_WINDOWS
-    -- ** Config options (Posix)
     , ignoreTrailingSeparators
     , ignoreCase
     , allowRelativeEquality
-#endif
+
+    , eqPath
     )
 where
 
@@ -186,3 +189,5 @@ where
 -}
 
 import Streamly.Internal.FileSystem.Path
+
+#include "DocTestFileSystemPath.hs"

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

@@ -1,3 +1,4 @@
+{-# LANGUAGE CPP #-}
 -- |
 -- Module      : Streamly.Internal.FileSystem.Path
 -- Copyright   : (c) 2023 Composewell Technologies