Add begins/ends/contains and clarify sed. Fixes #49

src/Turtle/Pattern.hs

@@ -81,6 +81,9 @@ module Turtle.Pattern (
     , prefix
     , suffix
     , has
+    , begins
+    , ends
+    , contains
     , invert
     , once
     , star
@@ -480,6 +483,42 @@ suffix p = chars *> p
 has :: Pattern a -> Pattern a
 has p = chars *> p <* chars
 
+{-| Match the entire string if it begins with the given pattern
+
+    This returns the entire string, not just the matched prefix
+
+>>> match (begins  "A"             ) "ABC"
+["ABC"]
+>>> match (begins ("A" *> pure "1")) "ABC"
+["1BC"]
+-}
+begins :: Pattern Text -> Pattern Text
+begins pattern = pattern <> chars
+
+{-| Match the entire string if it ends with the given pattern
+
+    This returns the entire string, not just the matched prefix
+
+>>> match (ends  "C"             ) "ABC"
+["ABC"]
+>>> match (ends ("C" *> pure "1")) "ABC"
+["AB1"]
+-}
+ends :: Pattern Text -> Pattern Text
+ends pattern = chars <> pattern
+
+{-| Match the entire string if it contains the given pattern
+
+    This returns the entire string, not just the interior pattern
+
+>>> match (contains  "B"             ) "ABC"
+["ABC"]
+>>> match (contains ("B" *> pure "1")) "ABC"
+["A1C"]
+-}
+contains :: Pattern Text -> Pattern Text
+contains pattern = chars <> pattern <> chars
+
 {-| Parse 0 or more occurrences of the given character
 
 >>> match (star anyChar) "123"

src/Turtle/Prelude.hs

@@ -985,8 +985,15 @@ grep pattern s = do
 
 {-| Replace all occurrences of a `Pattern` with its `Text` result
 
+    `sed` performs substitution on a line-by-line basis, meaning that
+    substitutions may not span multiple lines.  Additionally, substitutions may
+    occur multiple times within the same line, like the behavior of
+    @s/.../.../g@.
+
     Warning: Do not use a `Pattern` that matches the empty string, since it will
-    match an infinite number of times
+    match an infinite number of times.  `sed` tries to detect such `Pattern`s
+    and `die` with an error message if they occur, but this detection is
+    necessarily incomplete.
 -}
 sed :: Pattern Text -> Shell Text -> Shell Text
 sed pattern s = do