@@ -385,7 +385,7 @@ satisfy = D.toParserK . D.satisfy
388−-- S.chunksOf n f = S.splitParse (FL.take n f)
388+-- S.chunksOf n f = S.parseMany (FL.take n f)
391-- /Internal/
391-- /Internal/
@@ -457,23 +457,51 @@ takeWhile cond = D.toParserK . D.takeWhile cond
457takeWhile1 :: MonadCatch m => (a -> Bool) -> Fold m a b -> Parser m a b
457takeWhile1 :: MonadCatch m => (a -> Bool) -> Fold m a b -> Parser m a b
458takeWhile1 cond = D.toParserK . D.takeWhile1 cond
458takeWhile1 cond = D.toParserK . D.takeWhile1 cond
460−-- | Collect stream elements until an element succeeds the predicate. Drop the
460+-- Note: Keep this consistent with S.splitOn. In fact we should eliminate
461−-- element on which the predicate succeeded. The succeeding element is treated
461+-- S.splitOn in favor of the parser.
462−-- as an infix separator which is dropped from the output.
464−-- * Stops - when the predicate succeeds.
463+-- | Split on an infixed separator element, dropping the separator. Splits the
465−-- * Fails - never.
464+-- stream on separator elements determined by the supplied predicate, separator
465+-- is considered as infixed between two segments, if one side of the separator
466+-- is missing then it is parsed as an empty stream. The supplied 'Fold' is
467+-- applied on the split segments. With '-' representing non-separator elements
468+-- and '.' as separator, 'splitOn' splits as follows:
467−-- >>> S.parse (PR.sliceSepBy (== 1) FL.toList) $ S.fromList [0,0,1,0,1]
470+-- @
468−-- > [0,0]
471+-- "--.--" => "--" "--"
470−-- S.splitOn pred f = S.splitParse (PR.sliceSepBy pred f)
476+-- @PR.sliceSepBy (== x)@ is an inverse of @S.intercalate (S.yield x)@
472−-- >>> S.toList $ S.splitParse (PR.sliceSepBy (== 1) FL.toList) $ S.fromList [0,0,1,0,1]
478+-- Let's use the following definition for illustration:
475−-- /Internal/
480+-- > splitOn p = PR.many FL.toList $ PR.sliceSepBy p (FL.toList)
481+-- > splitOn' p = S.parse (splitOn p) . S.fromList
483+-- >>> splitOn' (== '.') ""
486+-- >>> splitOn' (== '.') "."
489+-- >>> splitOn' (== '.') ".a"
492+-- >>> splitOn' (== '.') "a."
495+-- >>> splitOn' (== '.') "a.b"
498+-- >>> splitOn' (== '.') "a..b"
501+-- * Stops - when the predicate succeeds.
477{-# INLINABLE sliceSepBy #-}
505{-# INLINABLE sliceSepBy #-}
478sliceSepBy :: MonadCatch m => (a -> Bool) -> Fold m a b -> Parser m a b
506sliceSepBy :: MonadCatch m => (a -> Bool) -> Fold m a b -> Parser m a b
479sliceSepBy cond = D.toParserK . D.sliceSepBy cond
507sliceSepBy cond = D.toParserK . D.sliceSepBy cond
@@ -485,7 +513,7 @@ sliceSepBy cond = D.toParserK . D.sliceSepBy cond
485-- * Stops - when the predicate succeeds.
513-- * Stops - when the predicate succeeds.
486-- * Fails - never.
514-- * Fails - never.
488−-- S.splitWithSuffix pred f = S.splitParse (PR.sliceEndWith pred f)
516+-- S.splitWithSuffix pred f = S.parseMany (PR.sliceEndWith pred f)
490-- /Unimplemented/
518-- /Unimplemented/
@@ -504,7 +532,7 @@ sliceEndWith = undefined
504-- * Stops - when the predicate succeeds in non-leading position.
532-- * Stops - when the predicate succeeds in non-leading position.
505-- * Fails - never.
533-- * Fails - never.
507−-- S.splitWithPrefix pred f = S.splitParse (PR.sliceBeginWith pred f)
535+-- S.splitWithPrefix pred f = S.parseMany (PR.sliceBeginWith pred f)
509-- /Unimplemented/
537-- /Unimplemented/
@@ -514,19 +542,39 @@ sliceBeginWith ::
514 (a -> Bool) -> Fold m a b -> Parser m a b
542 (a -> Bool) -> Fold m a b -> Parser m a b
515sliceBeginWith = undefined
543sliceBeginWith = undefined
517−-- | Split using a condition or a count whichever occurs first. This is a
545+-- | Like 'sliceSepBy' but terminates a parse even before the separator
518−-- hybrid of 'splitOn' and 'take'. The element on which the condition succeeds
546+-- is encountered if its size exceeds the specified maximum limit.
521−-- >>> even n = n `mod` 2 == 0
548+-- > take n = PR.sliceSepByMax (const True) n
522−-- >>> S.parse (PR.many FL.toList (PR.sliceSepByMax (==1) 5 FL.toList)) $ S.fromList [1..10]
549+-- > sliceSepBy p = PR.sliceSepByMax p maxBound
523−-- > [[],[2,3,4,5,6],[7,8,9,10]]
525−-- >>> S.parse (PR.many FL.toList (PR.sliceSepByMax even 10 FL.toList)) $ S.fromList [0..10]
551+-- Let's use the following definitions for illustration:
526−-- > [[],[1],[3],[5],[7],[9],[]]
528−-- /Internal/
553+-- > splitOn p n = PR.many FL.toList $ PR.sliceSepByMax p n (FL.toList)
554+-- > splitOn' p n = S.parse (splitOn p n) . S.fromList
556+-- >>> splitOn' (== '.') 0 ""
559+-- >>> splitOn' (== '.') 0 "a"
560+-- infinite list of empty strings
562+-- >>> splitOn' (== '.') 3 "hello.world"
563+-- ["hel","lo","wor","ld"]
565+-- If the separator is found and the limit is reached at the same time then it
566+-- behaves just like 'sliceSepBy' i.e. the separator is dropped.
568+-- >>> splitOn' (== '.') 0 "."
571+-- >>> splitOn' (== '.') 0 ".."
574+-- * Stops - when the predicate succeeds or the limit is reached.
530{-# INLINABLE sliceSepByMax #-}
578{-# INLINABLE sliceSepByMax #-}
531sliceSepByMax :: MonadCatch m
579sliceSepByMax :: MonadCatch m
532 => (a -> Bool) -> Int -> Fold m a b -> Parser m a b
580 => (a -> Bool) -> Int -> Fold m a b -> Parser m a b
@@ -541,7 +589,7 @@ sliceSepByMax cond cnt = D.toParserK . D.sliceSepByMax cond cnt
541-- * Fails - never.
589-- * Fails - never.
544−-- S.wordsBy pred f = S.splitParse (PR.wordBy pred f)
592+-- S.wordsBy pred f = S.parseMany (PR.wordBy pred f)
547-- /Unimplemented/
595-- /Unimplemented/
@@ -563,7 +611,7 @@ wordBy = undefined
563-- * Fails - never.
611-- * Fails - never.
566−-- S.groupsBy cmp f = S.splitParse (PR.groupBy cmp f)
614+-- S.groupsBy cmp f = S.parseMany (PR.groupBy cmp f)
569-- /Unimplemented/
617-- /Unimplemented/