HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Moduleturtle-1.6.2Haskell2010

Turtle.Pattern

Use this module to either:

  • match Text with light-weight backtracking patterns, or:

  • parse structured values from Text.

Example usage:

Example4 expressions
:set -XOverloadedStringsmatch ("can" <|> "cat") "cat"["cat"]match ("can" <|> "cat") "dog"[]match (decimal `sepBy` ",") "1,2,3"[[1,2,3]]

This pattern has unlimited backtracking, and will return as many solutions as possible:

Example1 expression
match (prefix (star anyChar)) "123"["123","12","1",""]

Use do notation to structure more complex patterns:

Example1 expression
:{let bit = ("0" *> pure False) <|> ("1" *> pure True) :: Pattern Bool;    portableBitMap = do        { "P1"        ; width  <- spaces1 *> decimal        ; height <- spaces1 *> decimal        ; count width (count height (spaces1 *> bit))        };in  match (prefix portableBitMap) "P1\n2 2\n0 0\n1 0\n":}[[[False,False],[True,False]]]
  • 1 type
  • 51 values
  • Packageturtle-1.6.2
  • Exports52
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourcePattern.hs

Pattern

2 declarations
newtypenewtype Pattern a
#

A fully backtracking pattern that parses an 'a' from some Text

Instances9Monad, Functor, Applicative, Alternative, MonadPlus, Num, …

Primitive patterns

2 declarations
valueanyChar :: Pattern Char
#

Match any character

Example2 expressions
match anyChar "1""1"match anyChar """"
valueeof :: Pattern ()
#

Matches the end of input

Example2 expressions
match eof "1"[]match eof ""[()]

Character patterns

21 declarations
valuesatisfy :: (Char -> Bool) -> Pattern Char
#

Match any character that satisfies the given predicate

Example2 expressions
match (satisfy (== '1')) "1""1"match (satisfy (== '2')) "1"""
valuechar :: Char -> Pattern Char
#

Match a specific character

Example2 expressions
match (char '1') "1""1"match (char '2') "1"""
valuenotChar :: Char -> Pattern Char
#

Match any character except the given one

Example2 expressions
match (notChar '2') "1""1"match (notChar '1') "1"""
valuetext :: Text -> Pattern Text
#

Match a specific string

Example1 expression
match (text "123") "123"["123"]

You can also omit the text function if you enable the OverloadedStrings extension:

Example1 expression
match "123" "123"["123"]
valueasciiCI :: Text -> Pattern Text
#

Match a specific string in a case-insensitive way

This only handles ASCII strings

Example1 expression
match (asciiCI "abc") "ABC"["ABC"]
valueoneOf :: [Char] -> Pattern Char
#

Match any one of the given characters

Example2 expressions
match (oneOf "1a") "1""1"match (oneOf "2a") "1"""
valuenoneOf :: [Char] -> Pattern Char
#

Match anything other than the given characters

Example2 expressions
match (noneOf "2a") "1""1"match (noneOf "1a") "1"""
valuespace :: Pattern Char
#

Match a whitespace character

Example2 expressions
match space " "" "match space "1"""
valuespaces :: Pattern Text
#

Match zero or more whitespace characters

Example2 expressions
match spaces "  "["  "]match spaces ""[""]
valuespaces1 :: Pattern Text
#

Match one or more whitespace characters

Example2 expressions
match spaces1 "  "["  "]match spaces1 ""[]
valuetab :: Pattern Char
#

Match the tab character ('t')

Example2 expressions
match tab "\t""\t"match tab " """
valuenewline :: Pattern Char
#

Match the newline character ('n')

Example2 expressions
match newline "\n""\n"match newline " """
valuecrlf :: Pattern Text
#

Matches a carriage return ('r') followed by a newline ('n')

Example2 expressions
match crlf "\r\n"["\r\n"]match crlf "\n\r"[]
valueupper :: Pattern Char
#

Match an uppercase letter

Example2 expressions
match upper "A""A"match upper "a"""
valuelower :: Pattern Char
#

Match a lowercase letter

Example2 expressions
match lower "a""a"match lower "A"""
valuealphaNum :: Pattern Char
#

Match a letter or digit

Example4 expressions
match alphaNum "1""1"match alphaNum "a""a"match alphaNum "A""A"match alphaNum "."""
valueletter :: Pattern Char
#

Match a letter

Example3 expressions
match letter "A""A"match letter "a""a"match letter "1"""
valuedigit :: Pattern Char
#

Match a digit

Example2 expressions
match digit "1""1"match digit "a"""
valuehexDigit :: Pattern Char
#

Match a hexadecimal digit

Example4 expressions
match hexDigit "1""1"match hexDigit "A""A"match hexDigit "a""a"match hexDigit "g"""
valueoctDigit :: Pattern Char
#

Match an octal digit

Example2 expressions
match octDigit "1""1"match octDigit "9"""

Numbers

2 declarations
valuedecimal :: Num n => Pattern n
#

Match an unsigned decimal number

Example2 expressions
match decimal  "123"[123]match decimal "-123"[]
valuesigned :: Num a => Pattern a -> Pattern a
#

Transform a numeric parser to accept an optional leading '+' or '-' sign

Example3 expressions
match (signed decimal) "+123"[123]match (signed decimal) "-123"[-123]match (signed decimal)  "123"[123]

Combinators

23 declarations
valueprefix :: Pattern a -> Pattern a
#

Use this to match the prefix of a string

Example2 expressions
match         "A"  "ABC"[]match (prefix "A") "ABC"["A"]
valuesuffix :: Pattern a -> Pattern a
#

Use this to match the suffix of a string

Example2 expressions
match         "C"  "ABC"[]match (suffix "C") "ABC"["C"]
valuehas :: Pattern a -> Pattern a
#

Use this to match the interior of a string

Example2 expressions
match      "B"  "ABC"[]match (has "B") "ABC"["B"]
valuebegins :: Pattern Text -> Pattern Text
#

Match the entire string if it begins with the given pattern

This returns the entire string, not just the matched prefix

Example2 expressions
match (begins  "A"             ) "ABC"["ABC"]match (begins ("A" *> pure "1")) "ABC"["1BC"]
valueends :: Pattern Text -> Pattern Text
#

Match the entire string if it ends with the given pattern

This returns the entire string, not just the matched prefix

Example2 expressions
match (ends  "C"             ) "ABC"["ABC"]match (ends ("C" *> pure "1")) "ABC"["AB1"]
valuecontains :: Pattern Text -> Pattern Text
#

Match the entire string if it contains the given pattern

This returns the entire string, not just the interior pattern

Example2 expressions
match (contains  "B"             ) "ABC"["ABC"]match (contains ("B" *> pure "1")) "ABC"["A1C"]
valueinvert :: Pattern a -> Pattern ()
#

(invert p) succeeds if p fails and fails if p succeeds

Example3 expressions
match (invert "A") "A"[]match (invert "A") "B"[()]match (invert "A") "AA"[()]
valuestar :: Pattern Char -> Pattern Text
#

Parse 0 or more occurrences of the given character

Example2 expressions
match (star anyChar) "123"["123"]match (star anyChar) ""[""]

See also: chars

valueplus :: Pattern Char -> Pattern Text
#

Parse 1 or more occurrences of the given character

Example2 expressions
match (plus digit) "123"["123"]match (plus digit) ""[]

See also: chars1

valueselfless :: Pattern a -> Pattern a
#

Patterns that match multiple times are greedy by default, meaning that they try to match as many times as possible. The selfless combinator makes a pattern match as few times as possible

This only changes the order in which solutions are returned, by prioritizing less greedy solutions

Example2 expressions
match (prefix (selfless (some anyChar))) "123"["1","12","123"]match (prefix           (some anyChar) ) "123"["123","12","1"]
valuechoice :: [Pattern a] -> Pattern a
#

Apply the patterns in the list in order, until one of them succeeds

Example3 expressions
match (choice ["cat", "dog", "egg"]) "egg"["egg"]match (choice ["cat", "dog", "egg"]) "cat"["cat"]match (choice ["cat", "dog", "egg"]) "fan"[]
valuecount :: Int -> Pattern a -> Pattern [a]
#

Apply the given pattern a fixed number of times, collecting the results

Example2 expressions
match (count 3 anyChar) "123"["123"]match (count 4 anyChar) "123"[]
valuelowerBounded :: Int -> Pattern a -> Pattern [a]
#

Apply the given pattern at least the given number of times, collecting the results

Example2 expressions
match (lowerBounded 5 dot) "123"[]match (lowerBounded 2 dot) "123"["123"]
valueupperBounded :: Int -> Pattern a -> Pattern [a]
#

Apply the given pattern 0 or more times, up to a given bound, collecting the results

Example3 expressions
match (upperBounded 5 dot) "123"["123"]match (upperBounded 2 dot) "123"[]match ((,) <$> upperBounded 2 dot <*> chars) "123"[("12","3"),("1","23")]
valuebounded :: Int -> Int -> Pattern a -> Pattern [a]
#

Apply the given pattern a number of times restricted by given lower and upper bounds, collecting the results

Example3 expressions
match (bounded 2 5 "cat") "catcatcat"[["cat","cat","cat"]]match (bounded 2 5 "cat") "cat"[]match (bounded 2 5 "cat") "catcatcatcatcatcat"[]

bounded could be implemented naively as follows:

bounded m n p = do
  x <- choice (map pure [m..n])
  count x p
valueoption :: Monoid a => Pattern a -> Pattern a
#

Transform a parser to a succeed with an empty value instead of failing

See also: optional

Example2 expressions
match (option "1" <> "2") "12"["12"]match (option "1" <> "2") "2"["2"]
valuebetween :: Pattern a -> Pattern b -> Pattern c -> Pattern c
#

(between open close p) matches 'p' in between 'open' and 'close'

Example2 expressions
match (between (char '(') (char ')') (star anyChar)) "(123)"["123"]match (between (char '(') (char ')') (star anyChar)) "(123"[]
valueskip :: Pattern a -> Pattern ()
#

Discard the pattern's result

Example2 expressions
match (skip anyChar) "1"[()]match (skip anyChar) ""[]
valuewithin :: Int -> Pattern a -> Pattern a
#

Restrict the pattern to consume no more than the given number of characters

Example3 expressions
match (within 2 decimal) "12"[12]match (within 2 decimal) "1"[1]match (within 2 decimal) "123"[]
valuefixed :: Int -> Pattern a -> Pattern a
#

Require the pattern to consume exactly the given number of characters

Example2 expressions
match (fixed 2 decimal) "12"[12]match (fixed 2 decimal) "1"[]
valuesepBy :: Pattern a -> Pattern b -> Pattern [a]
#

p sepBy sep matches zero or more occurrences of p separated by sep

Example2 expressions
match (decimal `sepBy` char ',') "1,2,3"[[1,2,3]]match (decimal `sepBy` char ',') ""[[]]
valuesepBy1 :: Pattern a -> Pattern b -> Pattern [a]
#

p sepBy1 sep matches one or more occurrences of p separated by sep

Example2 expressions
match (decimal `sepBy1` ",") "1,2,3"[[1,2,3]]match (decimal `sepBy1` ",") ""[]

High-efficiency primitives

2 declarations