Regex.elm

module Regex
    ( Regex
    , regex, escape, caseInsensitive
    , HowMany(..), Match
    , contains, find, replace, split
    ) where

{-| A library for working with regular expressions. It uses [the
same kind of regular expressions accepted by JavaScript](https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions).

# Create
@docs Regex, regex, escape, caseInsensitive

# Helpful Data Structures

These data structures are needed to help define functions like [`find`](#find)
and [`replace`](#replace).

@docs HowMany, Match

# Use
@docs contains, find, replace, split

-}

import Maybe exposing (Maybe)
import Native.Regex


{-| A regular expression, describing a certain set of strings.
-}
type Regex = Regex


{-| Escape strings to be regular expressions, making all special characters
safe. So `regex (escape "^a+")` will match exactly `"^a+"` instead of a series
of `a`’s that start at the beginning of the line.
-}
escape : String -> String
escape =
  Native.Regex.escape


{-| 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).

Be careful to escape backslashes properly! For example, `"\w"` is escaping the
letter `w` which is probably not what you want. You probably want `"\\w"`
instead, which escapes the backslash.
-}
regex : String -> Regex
regex =
  Native.Regex.regex



{-| Make a regex case insensitive -}
caseInsensitive : Regex -> Regex
caseInsensitive =
  Native.Regex.caseInsensitive


{-| Check to see if a Regex is contained in a string.

    contains (regex "123") "12345" == True
    contains (regex "b+") "aabbcc" == True

    contains (regex "789") "12345" == False
    contains (regex "z+") "aabbcc" == False
-}
contains : Regex -> String -> Bool
contains =
  Native.Regex.contains


{-| A `Match` represents all of the details about a particular match in a string.
Here are details on each field:

  * `match` — the full string of the match.
  * `submatches` — a regex might have [subpatterns, surrounded by
    parentheses](https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions#Using_Parenthesized_Substring_Matches).
    If there are N subpatterns, there will be N elements in the `submatches` list.
    Each submatch in this list is a `Maybe` because not all subpatterns may trigger.
    For example, `(regex "(a+)|(b+)")` will either match many `a`’s or
    many `b`’s, but never both.
  * `index` — the index of the match in the original string.
  * `number` — if you find many matches, you can think of each one
    as being labeled with a `number` starting at one. So the first time you
    find a match, that is match `number` one. Second time is match `number` two.
    This is useful when paired with `replace All` if replacement is dependent on how
    many times a pattern has appeared before.
-}
type alias Match =
    { match : String
    , submatches : List (Maybe String)
    , index : Int
    , number : Int
    }


{-| `HowMany` is used to specify how many matches you want to make. So
`replace All` would replace every match, but `replace (AtMost 2)` would
replace at most two matches (i.e. zero, one, two, but never three or more).
-}
type HowMany = All | AtMost Int


{-| Find matches in a string:

    findTwoCommas = find (AtMost 2) (regex ",")

      -- map .index (findTwoCommas "a,b,c,d,e") == [1,3]
      -- map .index (findTwoCommas "a b c d e") == []

    places = find All (regex "[oi]n a (\\w+)") "I am on a boat in a lake."

      -- map .match places == ["on a boat", "in a lake"]
      -- map .submatches places == [ [Just "boat"], [Just "lake"] ]
-}
find : HowMany -> Regex -> String -> List Match
find =
  Native.Regex.find


{-| Replace matches. The function from `Match` to `String` lets
you use the details of a specific match when making replacements.

    devowel = replace All (regex "[aeiou]") (\_ -> "")

      -- devowel "The quick brown fox" == "Th qck brwn fx"

    reverseWords = replace All (regex "\\w+") (\{match} -> String.reverse match)

      -- reverseWords "deliver mined parts" == "reviled denim strap"
-}
replace : HowMany -> Regex -> (Match -> String) -> String -> String
replace =
  Native.Regex.replace


{-| Split a string, using the regex as the separator.

    split (AtMost 1) (regex ",") "tom,99,90,85" == ["tom","99,90,85"]

    split All (regex ",") "a,b,c,d" == ["a","b","c","d"]
-}
split : HowMany -> Regex -> String -> List String
split =
  Native.Regex.split