@@ -3,16 +3,17 @@ module Regex where
33same kind of regular expressions accepted by JavaScript](https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions).
44
55# Create
6−@docs pattern, caseInsensitive, escape
6+@docs regex, escape, caseInsensitive
77
8−# Match
9−@docs Match
8+# Helpful Data Structures
109
11−# Find and Replace
12−@docs contains, find, findAll, replace, replaceAll
10+These data structures are needed to help define functions like [`find`](#find)
11+and [`replace`](#replace).
1312
14−# Split
15−@docs split, splitN
13+@docs HowMany, Match
14+
15+# Use
16+@docs contains, find, replace, split
1617
1718-}
1819
@@ -21,31 +22,35 @@ import Native.Regex
2122
2223data Regex = Regex
2324
24−{-| Escape all special characters. So `pattern (escape "$$$")`
25−will match exactly `"$$$"` even though `$` is a special character.
25+{-| Escape strings to be regular expressions, making all special characters
26+safe. So `regex (escape "^a+")` will match exactly `"^a+"` instead of a series
27+of `a`’s that start at the beginning of the line.
2628-}
2729escape : String -> String
2830escape = Native.Regex.escape
2931
3032{-| Create a Regex that matches patterns [as specified in JavaScript](https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions#Writing_a_Regular_Expression_Pattern).
31−Be careful to escape backslashes properly!
33+
34+Be careful to escape backslashes properly! For example, `"\w"` is escaping the
35+letter `w` which is probably not what you want. You probably want `"\\w"`
36+instead, which escapes the backslash.
3237-}
33−pattern : String -> Regex
34−pattern = Native.Regex.pattern
38+regex : String -> Regex
39+regex = Native.Regex.regex
3540
3641
37−{-| Make a pattern case insensitive -}
42+{-| Make a regex case insensitive -}
3843caseInsensitive : Regex -> Regex
3944caseInsensitive = Native.Regex.caseInsensitive
4045
4146{-| Check to see if a Regex is contained in a string.
4247
4348```haskell
44− contains (pattern "123") "12345" == True
45− contains (pattern "b+") "aabbcc" == True
49+ contains (regex "123") "12345" == True
50+ contains (regex "b+") "aabbcc" == True
4651
47− contains (pattern "789") "12345" == False
48− contains (pattern "z+") "aabbcc" == False
52+ contains (regex "789") "12345" == False
53+ contains (regex "z+") "aabbcc" == False
4954```
5055-}
5156contains : Regex -> String -> Bool
@@ -55,79 +60,67 @@ contains = Native.Regex.contains
5560Here are details on each field:
5661
5762 * `match` — the full string of the match.
58− * `submatches` — a pattern might have [subpatterns, surrounded by
63+ * `submatches` — a regex might have [subpatterns, surrounded by
5964 parentheses](https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions#Using_Parenthesized_Substring_Matches).
6065 If there are N subpatterns, there will be N elements in the `submatches` list.
6166 Each submatch in this list is a `Maybe` because not all subpatterns may trigger.
62− For example, `(pattern "(a+)|(b+)")` will either match many `a`’s or
67+ For example, `(regex "(a+)|(b+)")` will either match many `a`’s or
6368 many `b`’s, but never both.
6469 * `index` — the index of the match in the original string.
6570 * `number` — if you find many matches, you can think of each one
6671 as being labeled with a `number` starting at one. So the first time you
6772 find a match, that is match `number` one. Second time is match `number` two.
68− This is useful when paired with `replaceAll` if replacement is dependent on how
73+ This is useful when paired with `replace All` if replacement is dependent on how
6974 many times a pattern has appeared before.
7075-}
7176type Match = { match : String, submatches : [Maybe String], index : Int, number : Int }
7277
73−{-| Find all of the matches in a string:
78+{-| `HowMany` is used to specify how many matches you want to make. So
79+`replace All` would replace every match, but `replace (AtMost 2)` would
80+replace at most two matches (i.e. zero, one, two, but never three or more).
81+-}
82+data HowMany = All | AtMost Int
83+
84+{-| Find matches in a string:
7485
7586```haskell
76− words = findAll (pattern "\\w+") "hello world"
87+ findTwoCommas = find (AtMost 2) (regex ",")
7788
78− map .match words == ["hello","world"]
79− map .index words == [0,6]
89+ -- map .index (findTwoCommas "a,b,c,d,e") == [1,3]
90+ -- map .index (findTwoCommas "a b c d e") == []
8091
81− places = findAll (pattern "[oi]n a (\\w+)") "I am on a boat in a lake."
92+ places = find All (regex "[oi]n a (\\w+)") "I am on a boat in a lake."
8293
83− map .match places== ["on a boat", "in a lake"]
84− map .submatches places == [ [Just "boat"], [Just "lake"] ]
94+ -- map .match places == ["on a boat", "in a lake"]
95+ -- map .submatches places == [ [Just "boat"], [Just "lake"] ]
8596```
8697-}
87−findAll : Regex -> String -> [Match]
88−findAll = Native.Regex.findAll
89−
90−{-| Same as `findAll`, but `find` will quit searching after the *n<sup>th</sup>* match.
91−That means the resulting list has maximum length N, but *it can be shorter*
92−if there are not that many matches in the given string.
93−-}
94−find : Int -> Regex -> String -> [Match]
98+find : HowMany -> Regex -> String -> [Match]
9599find = Native.Regex.find
96100
97−{-| Replace all matches. The function from `Match` to `String` lets
101+{-| Replace matches. The function from `Match` to `String` lets
98102you use the details of a specific match when making replacements.
99103
100104```haskell
101− devowel = replaceAll (pattern "[aeiou]") (\_ -> "")
105+ devowel = replace All (regex "[aeiou]") (\_ -> "")
102106
103− devowel "The quick brown fox" == "Th qck brwn fx"
107+ -- devowel "The quick brown fox" == "Th qck brwn fx"
104108
105− reverseWords = replaceAll (pattern "\\w+") (\{match} -> String.reverse match)
109+ reverseWords = replace All (regex "\\w+") (\{match} -> String.reverse match)
106110
107− reverseWords "deliver mined parts" == "reviled denim strap"
111+ -- reverseWords "deliver mined parts" == "reviled denim strap"
108112```
109113-}
110−replaceAll : Regex -> (Match -> String) -> String -> String
111−replaceAll = Native.Regex.replaceAll
112−
113−{-| Same as `replaceAll`, but `replace` will quit after the *n<sup>th</sup>* match.-}
114−replace : Int -> Regex -> (Match -> String) -> String -> String
114+replace : HowMany -> Regex -> (Match -> String) -> String -> String
115115replace = Native.Regex.replace
116116
117117{-| Split a string, using the regex as the separator.
118118
119119```haskell
120− split (pattern " *, *") "a ,b, c,d" == ["a","b","c","d"]
121−```
122−-}
123−split : Regex -> String -> [String]
124−split = Native.Regex.split
120+ split (AtMost 1) (regex ",") "tom,99,90,85" == ["tom","99,90,85"]
125121
126−{-| Same as `split` but stops after the *n<sup>th</sup>* match.
127−
128−```haskell
129− splitN 1 (pattern ": *") "tom: 99,90,85" == ["tom","99,90,85"]
122+ split All (regex ",") "a,b,c,d" == ["a","b","c","d"]
130123```
131124-}
132−splitN : Int -> Regex -> String -> [String]
133−splitN = Native.Regex.splitN
125+split : HowMany -> Regex -> String -> [String]
126+split = Native.Regex.split