Path refactoring

core/src/Streamly/Internal/Data/Array.hs

@@ -57,7 +57,7 @@ module Streamly.Internal.Data.Array
     -- , getSlice
     , sliceIndexerFromLen
     , slicerFromLen
-    , splitOn -- XXX slicesEndBy
+    , sliceEndBy_
 
     -- * Streaming Operations
     , streamTransform
@@ -101,6 +101,7 @@ module Streamly.Internal.Data.Array
     , pinnedCompactLE
     , compactOnByte
     , compactOnByteSuffix
+    , splitOn
     )
 where
 
@@ -310,12 +311,14 @@ getSliceUnsafe index len (Array contents start e) =
 -- matching the predicate is dropped.
 --
 -- /Pre-release/
-{-# INLINE splitOn #-}
-splitOn :: (Monad m, Unbox a) =>
+{-# INLINE sliceEndBy_ #-}
+sliceEndBy_, splitOn :: (Monad m, Unbox a) =>
     (a -> Bool) -> Array a -> Stream m (Array a)
-splitOn predicate arr =
+sliceEndBy_ predicate arr =
     fmap (\(i, len) -> getSliceUnsafe i len arr)
-        $ D.indexOnSuffix predicate (read arr)
+        $ D.indexEndBy_ predicate (read arr)
+
+RENAME(splitOn,sliceEndBy_)
 
 {-# INLINE sliceIndexerFromLen #-}
 sliceIndexerFromLen :: forall m a. (Monad m, Unbox a)

core/src/Streamly/Internal/Data/MutArray/Type.hs

@@ -257,7 +257,7 @@ module Streamly.Internal.Data.MutArray.Type
     -- | Split an array into slices.
 
     -- , getSlicesFromLenN
-    , splitOn -- slicesEndBy
+    , sliceEndBy_
     -- , slicesOf
 
     -- *** Concat
@@ -359,6 +359,7 @@ module Streamly.Internal.Data.MutArray.Type
     , pinnedFromList
     , pinnedClone
     , unsafePinnedCreateOf
+    , splitOn
     )
 where
 
@@ -2891,12 +2892,16 @@ spliceExp = spliceWith (\l1 l2 -> max (l1 * 2) (l1 + l2))
 -- matching the predicate is dropped.
 --
 -- /Pre-release/
-{-# INLINE splitOn #-}
-splitOn :: (MonadIO m, Unbox a) =>
+{-# INLINE sliceEndBy_ #-}
+sliceEndBy_, splitOn :: (MonadIO m, Unbox a) =>
     (a -> Bool) -> MutArray a -> Stream m (MutArray a)
-splitOn predicate arr =
+sliceEndBy_ predicate arr =
     fmap (\(i, len) -> unsafeGetSlice i len arr)
-        $ D.indexOnSuffix predicate (read arr)
+        $ D.indexEndBy_ predicate (read arr)
+
+RENAME(splitOn,sliceEndBy_)
+
+-- XXX breakEndBy_?
 
 -- | Drops the separator byte
 {-# INLINE breakOn #-}

core/src/Streamly/Internal/Data/Stream/Type.hs

@@ -143,7 +143,7 @@ module Streamly.Internal.Data.Stream.Type
     , foldIterateBfs
 
     -- * Splitting
-    , indexOnSuffix
+    , indexEndBy_
 
     -- * Multi-stream folds
     -- | These should probably be expressed using zipping operations.
@@ -153,6 +153,7 @@ module Streamly.Internal.Data.Stream.Type
     -- * Deprecated
     , sliceOnSuffix
     , unfoldMany
+    , indexOnSuffix
     )
 where
 
@@ -2114,25 +2115,27 @@ indexerBy (Fold step1 initial1 extract1 _final) n =
 
     extract (Tuple' i s) = (i,) <$> extract1 s
 
--- XXX rename to indicesEndBy
-
--- | Like 'splitEndBy' but generates a stream of (index, len) tuples marking
+-- | Like 'splitEndBy_' but generates a stream of (index, len) tuples marking
 -- the places where the predicate matches in the stream.
 --
+-- >>> Stream.toList $ Stream.indexEndBy_ (== '/') $ Stream.fromList "/home/harendra"
+-- [(0,0),(1,4),(6,8)]
+--
 -- /Pre-release/
-{-# INLINE indexOnSuffix #-}
-indexOnSuffix :: Monad m =>
+{-# INLINE indexEndBy_ #-}
+indexEndBy_, indexOnSuffix :: Monad m =>
     (a -> Bool) -> Stream m a -> Stream m (Int, Int)
-indexOnSuffix predicate =
-    -- Scan the stream with the given refold
+indexEndBy_ predicate =
     refoldIterateM
         (indexerBy (FL.takeEndBy_ predicate FL.length) 1)
         (return (-1, 0))
 
+RENAME(indexOnSuffix,indexEndBy_)
+
 -- Alternate implementation
-{-# INLINE_NORMAL _indexOnSuffix #-}
-_indexOnSuffix :: Monad m => (a -> Bool) -> Stream m a -> Stream m (Int, Int)
-_indexOnSuffix p (Stream step1 state1) = Stream step (Just (state1, 0, 0))
+{-# INLINE_NORMAL _indexEndBy_ #-}
+_indexEndBy_ :: Monad m => (a -> Bool) -> Stream m a -> Stream m (Int, Int)
+_indexEndBy_ p (Stream step1 state1) = Stream step (Just (state1, 0, 0))
 
     where
 
@@ -2149,9 +2152,9 @@ _indexOnSuffix p (Stream step1 state1) = Stream step (Just (state1, 0, 0))
               Stop -> if len == 0 then Stop else Yield (i, len) Nothing
     step _ Nothing = return Stop
 
-{-# DEPRECATED sliceOnSuffix "Please use indexOnSuffix instead." #-}
+{-# DEPRECATED sliceOnSuffix "Please use indexEndBy_ instead." #-}
 sliceOnSuffix :: Monad m => (a -> Bool) -> Stream m a -> Stream m (Int, Int)
-sliceOnSuffix = indexOnSuffix
+sliceOnSuffix = indexEndBy_
 
 ------------------------------------------------------------------------------
 -- Stream with a cross product style monad instance

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

@@ -17,17 +17,36 @@
 -- 'Path' type.
 --
 -- The basic type-safety is provided by the
--- "Streamly.Internal.FileSystem.PosixPath.LocSeg" module. We make a distinction
--- between two types of paths viz. locations and segments. Locations are
--- represented by the @Loc Path@ type and path segments are represented by the
--- @Seg Path@ type. Locations are paths pointing to specific objects in the
--- file system absolute or relative e.g. @\/usr\/bin@, @.\/local\/bin@, or @.@.
--- Segments are a sequence of path components without any reference to a
--- location e.g. @usr\/bin@, @local\/bin@, or @../bin@ are segments. This
--- distinction is for safe append operation on paths, you can only append
--- segments to any path and not a location. If you use the 'Path' type then
--- append can fail if you try to append a location to a path, but if you use
--- @Loc Path@ or @Seg Path@ types then append can never fail.
+-- "Streamly.Internal.FileSystem.PosixPath.LocSeg" module. We make a
+-- distinction between two types of paths viz. locations and segments.
+-- Locations are represented by the @Loc Path@ type and path segments are
+-- represented by the @Seg Path@ type.
+--
+-- Locations are rooted paths, they have a "root" attached to them. 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, nevertheless these are rooted
+-- paths as they still refer to a specific location starting from some root in
+-- the file system even though the root is decided dynamically.
+--
+-- In contrast to rooted paths, path segments are simply a sequence of path
+-- components without any reference to a root or specific starting location
+-- e.g. @usr\/bin@, @local\/bin@, or @../bin@ are simply path segments which
+-- can be attached to any other path or segment to augment it. This distinction
+-- is made to allow for safe append operation on paths, you can only append
+-- path segments to any path, a rooted path cannot be appended to another path.
+-- 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.
+--
+-- To summarize the conceptual distinctions:
+-- * Path
+--   * Rooted location
+--     * Absolute
+--     * Relative
+--   * Unrooted segment
 --
 -- Independently of the location or segment distinction you can also make the
 -- distinction between files and directories using the