Merge pull request #194 from purescript-contrib/replace2

replaceT instead of streamEditT

Author: jamesdbrock

CHANGELOG.md

@@ -48,6 +48,11 @@ New features:
 - Add the `anyTill` primitive `String` combinator. (#186 by @jamesdbrock)
 - Add the `Parsing.String.Replace` module, copied from
   https://github.com/jamesdbrock/purescript-parsing-replace (#188 by @jamesdbrock)
+  `streamEditT` can be written in terms of `replaceT`.
+
+  `streamEditT input sep editor = replaceT input (sep >>= editor >>> lift)`
+
+  (#188 by @jamesdbrock, #194 by @jamesdbrock)
 - Add the `advance` and `manyIndex` combinators. (#193 by @jamesdbrock)
 
 Bugfixes:

src/Parsing/String/Replace.purs

@@ -63,8 +63,8 @@ module Parsing.String.Replace
   , breakCapT
   , splitCap
   , splitCapT
-  , streamEdit
-  , streamEditT
+  , replace
+  , replaceT
   ) where
 
 import Prelude
@@ -81,7 +81,7 @@ import Data.List (List(..), foldl, uncons, (:))
 import Data.List as List
 import Data.List.NonEmpty (NonEmptyList, fromList, singleton)
 import Data.Maybe (Maybe(..), fromJust, isJust, maybe)
-import Data.Newtype (unwrap, wrap)
+import Data.Newtype (unwrap)
 import Data.Nullable (Nullable, notNull, null)
 import Data.String (CodePoint, joinWith)
 import Data.String as CodePoint
@@ -410,20 +410,20 @@ splitCap
   -> NonEmptyList (Either String a)
 splitCap input sep = unwrap $ splitCapT input sep
 
--- | Monad transformer version of `streamEdit`. The `sep` parser and the
--- | `editor` function will both run in the monad context.
+-- | Monad transformer version of `replace`.
 -- |
 -- | #### Example
 -- |
 -- | Find an environment variable in curly braces and replace it with its value
 -- | from the environment.
--- | We can read from the environment because `streamEditT` is running the
--- | `editor` function in `Effect`.
+-- | We can read from the environment with `lookupEnv` because `replaceT` is
+-- | running the `sep` parser in `Effect`.
 -- |
 -- | ```purescript
--- | pattern = string "{" *> anyTill (string "}")
--- | editor  = fst >>> lookupEnv >=> fromMaybe "" >>> pure
--- | streamEditT "◀ {HOME} ▶" pattern editor
+-- | replaceT "◀ {HOME} ▶" do
+-- |   _ <- string "{"
+-- |   Tuple home _ <- anyTill (string "}")
+-- |   lift (lookupEnv home) >>= maybe empty pure
 -- | ```
 -- |
 -- | Result:
@@ -433,15 +433,14 @@ splitCap input sep = unwrap $ splitCapT input sep
 -- | ```
 -- |
 -- | [![Perl Problems](https://imgs.xkcd.com/comics/perl_problems.png)](https://xkcd.com/1171/)
-streamEditT
-  :: forall m a
+replaceT
+  :: forall m
    . (Monad m)
   => (MonadRec m)
   => String
-  -> ParserT String m a
-  -> (a -> m String)
+  -> ParserT String m String
   -> m String
-streamEditT input sep editor = do
+replaceT input sep = do
   runParserT input (Tuple <$> (splitCapCombinator sep) <*> rest) >>= case _ of
     Left _ -> pure input
     Right (Tuple { carry, rlist, arraySize } remain) -> do
@@ -459,13 +458,12 @@ streamEditT input sep editor = do
 
       let
         accum
-          :: { index :: Int, rlist' :: List (Tuple String a) }
-          -> m (Step { index :: Int, rlist' :: List (Tuple String a) } Unit)
+          :: { index :: Int, rlist' :: List (Tuple String String) }
+          -> m (Step { index :: Int, rlist' :: List (Tuple String String) } Unit)
         accum { index, rlist' } = case uncons rlist' of
           Nothing -> pure $ Done unit
           Just { head: Tuple unmatched matched, tail } -> do
-            edited <- editor matched
-            doST $ unsafePartial $ Array.ST.Partial.poke index (notNull edited) arr
+            doST $ unsafePartial $ Array.ST.Partial.poke index (notNull matched) arr
             if String.null unmatched then
               do
                 pure $ Loop { index: index - 1, rlist': tail }
@@ -487,12 +485,13 @@ streamEditT input sep editor = do
   doST = pure <<< unsafePerformEffect <<< toEffect
 
 -- |
--- | #### Stream editor
+-- | #### Find-and-replace
 -- |
--- | Also known as “find-and-replace”, or “match-and-substitute”. Find all
+-- | Also called “match-and-substitute”. Find all
 -- | of the leftmost non-overlapping sections of the input string which match
 -- | the pattern parser `sep`, and
--- | replace them with the result of the `editor` function.
+-- | replace them with the result of the parser.
+-- | The `sep` parser must return a result of type `String`.
 -- |
 -- | This function can be used instead of
 -- | [Data.String.replaceAll](https://pursuit.purescript.org/packages/purescript-strings/docs/Data.String#v:replaceAll)
@@ -501,39 +500,47 @@ streamEditT input sep editor = do
 -- |
 -- | #### Access the matched section of text in the `editor`
 -- |
--- | If you want access to the matched string in the `editor` function,
--- | then combine the pattern parser `sep`
--- | with `match`. This will effectively change
--- | the type of the `editor` function to `(String /\ a) -> String`.
--- |
--- | This allows us to write an `editor` function which can choose to not
--- | edit the match and just leave it as it is. If the `editor` function
--- | returns the first item in the tuple, then `streamEdit` will not change
--- | the matched string.
+-- | To get access to the matched string for the replacement
+-- | combine the pattern parser `sep`
+-- | with `match`.
+-- | This allows us to write a `sep` parser which can choose to not
+-- | edit the match and just leave it as it is.
 -- |
 -- | So, for all `sep`:
 -- |
 -- | ```purescript
--- | streamEdit input (match sep) fst == input
+-- | replace input (fst <$> match sep) == input
 -- | ```
 -- |
 -- | #### Example
 -- |
 -- | Find and uppercase the `"needle"` pattern.
 -- |
 -- | ```purescript
--- | streamEdit "hay needle hay" (string "needle") toUpper
+-- | replace "hay needle hay" (toUpper <$> string "needle")
 -- | ```
 -- |
 -- | Result:
 -- |
 -- | ```purescript
 -- | "hay NEEDLE hay"
 -- | ```
-streamEdit
-  :: forall a
-   . String
-  -> Parser String a
-  -> (a -> String)
+-- |
+-- | #### Example
+-- |
+-- | Find integers and double them.
+-- |
+-- | ```purescript
+-- | replace "1 6 21 107" (show <$> (_*2) <$> intDecimal)
+-- | ```
+-- |
+-- | Result:
+-- |
+-- | ```purescript
+-- | "2 12 42 214"
+-- | ```
+replace
+  :: String
+  -> Parser String String
   -> String
-streamEdit input sep editor = unwrap $ streamEditT input sep (wrap <<< editor)
+replace input sep = unwrap $ replaceT input sep

test/Main.purs

@@ -9,7 +9,7 @@ import Prelude hiding (between, when)
 
 import Control.Alt ((<|>))
 import Control.Lazy (fix)
-import Control.Monad.State (State, modify, runState)
+import Control.Monad.State (State, lift, modify, runState)
 import Data.Array (some, toUnfoldable)
 import Data.Array as Array
 import Data.Bifunctor (lmap, rmap)
@@ -18,7 +18,7 @@ import Data.Foldable (oneOf)
 import Data.List (List(..), fromFoldable, (:))
 import Data.List.NonEmpty (NonEmptyList(..), catMaybes, cons, cons')
 import Data.List.NonEmpty as NE
-import Data.Maybe (Maybe(..), fromJust)
+import Data.Maybe (Maybe(..), fromJust, maybe)
 import Data.NonEmpty ((:|))
 import Data.Number (infinity, nan)
 import Data.Number as Data.Number
@@ -34,12 +34,12 @@ import Effect.Console (log, logShow)
 import Effect.Unsafe (unsafePerformEffect)
 import Node.Process (lookupEnv)
 import Parsing (ParseError(..), Parser, ParserT, Position(..), consume, fail, initialPos, parseErrorMessage, parseErrorPosition, position, region, runParser)
-import Parsing.Combinators (advance, between, chainl, chainl1, chainr, chainr1, choice, endBy, endBy1, lookAhead, many, many1, many1Till, many1Till_, manyIndex, manyTill, manyTill_, notFollowedBy, optionMaybe, sepBy, sepBy1, sepEndBy, sepEndBy1, skipMany, skipMany1, try, (<?>), (<??>), (<~?>))
+import Parsing.Combinators (advance, between, chainl, chainl1, chainr, chainr1, choice, empty, endBy, endBy1, lookAhead, many, many1, many1Till, many1Till_, manyIndex, manyTill, manyTill_, notFollowedBy, optionMaybe, sepBy, sepBy1, sepEndBy, sepEndBy1, skipMany, skipMany1, try, (<?>), (<??>), (<~?>))
 import Parsing.Expr (Assoc(..), Operator(..), buildExprParser)
 import Parsing.Language (haskellDef, haskellStyle, javaStyle)
 import Parsing.String (anyChar, anyCodePoint, anyTill, char, eof, match, regex, rest, satisfy, string, takeN)
-import Parsing.String.Basic (intDecimal, number, letter, noneOfCodePoints, oneOfCodePoints, whiteSpace)
-import Parsing.String.Replace (breakCap, splitCap, splitCapT, streamEdit, streamEditT)
+import Parsing.String.Basic (intDecimal, letter, noneOfCodePoints, number, oneOfCodePoints, whiteSpace)
+import Parsing.String.Replace (breakCap, replace, replaceT, splitCap, splitCapT)
 import Parsing.Token (TokenParser, makeTokenParser, token, when)
 import Parsing.Token as Token
 import Partial.Unsafe (unsafePartial)
@@ -951,20 +951,16 @@ main = do
     { actual: splitCap "abc" consume
     , expected: NonEmptyList $ Right unit :| Left "a" : Right unit : Left "b" : Right unit : Left "c" : Right unit : Nil
     }
-  assertEqual' "streamEdit1"
-    { actual: streamEdit "aBc" (match $ string "B") fst
-    , expected: "aBc"
-    }
-  assertEqual' "streamEdit2"
-    { actual: streamEdit "aBd" (string "B") (const "C")
+  assertEqual' "replace2"
+    { actual: replace "aBd" (string "B" *> pure "C")
     , expected: "aCd"
     }
-  assertEqual' "streamEdit3"
-    { actual: streamEdit "abcd" (takeN 1) toUpper
+  assertEqual' "replace3"
+    { actual: replace "abcd" (toUpper <$> takeN 1)
     , expected: "ABCD"
     }
-  assertEqual' "streamEdit4"
-    { actual: streamEdit "abc" (pure unit) (\_ -> "X")
+  assertEqual' "replace4"
+    { actual: replace "abc" (pure "X")
     , expected: "XaXbXcX"
     }
   assertEqual' "String.Replace example0"
@@ -979,10 +975,17 @@ main = do
     { actual: catMaybes $ hush <$> splitCap ".A...\n...A." (position <* string "A")
     , expected: (Position { index: 1, line: 1, column: 2 }) : (Position { index: 9, line: 2, column: 4 } : Nil)
     }
-  assertEqual' "String.Replace example3"
-    { actual: unsafePerformEffect $ streamEditT "◀ {HOME} ▶" (string "{" *> anyTill (string "}")) (fst >>> lookupEnv >=> unsafePartial fromJust >>> pure)
+  assertEqual' "String.Replace example3'"
+    { actual: unsafePerformEffect $ replaceT "◀ {HOME} ▶" do
+        _ <- string "{"
+        Tuple home _ <- anyTill (string "}")
+        lift (lookupEnv home) >>= maybe empty pure
     , expected: "◀ " <> unsafePartial (fromJust (unsafePerformEffect (lookupEnv "HOME"))) <> " ▶"
     }
+  assertEqual' "String.Replace example4'"
+    { actual: replace "1 6 21 107" (show <$> (_ * 2) <$> intDecimal)
+    , expected: "2 12 42 214"
+    }
   assertEqual' "String.Replace example4"
     { actual:
         let
@@ -1006,6 +1009,10 @@ main = do
           rmap fst <$> splitCap "((🌼)) (()())" (match balancedParens)
     , expected: NonEmptyList $ Right "((🌼))" :| Left " " : Right "(()())" : Nil
     }
+  assertEqual' "String.Replace example6"
+    { actual: replace "hay needle hay" (toUpper <$> string "needle")
+    , expected: "hay NEEDLE hay"
+    }
 
   log "\nTESTS manyIndex\n"