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

Moduleparsec-3.1.18.0Haskell2010

Text.Parsec.Perm

This module implements permutation parsers. The algorithm used is fairly complex since we push the type system to its limits :-) The algorithm is described in:

Parsing Permutation Phrases, by Arthur Baars, Andres Loh and Doaitse Swierstra. Published as a functional pearl at the Haskell Workshop 2001.

From the abstract:

A permutation phrase is a sequence of elements (possibly of different types) in which each element occurs exactly once and the order is irrelevant. Some of the permutable elements may be optional.

  • 2 types
  • 5 values
  • Packageparsec-3.1.18.0
  • Exports7
  • LanguageHaskell2010
  • LicenceBSD-2-Clause
  • SourcePerm.hs
datadata StreamPermParser s st a
#

The type StreamPermParser s st a denotes a permutation parser that, when converted by the permute function, parses s streams with user state st and returns a value of type a on success.

Normally, a permutation parser is first build with special operators like (<||>) and than transformed into a normal parser using permute.

valuepermute :: Stream s Identity tok => StreamPermParser s st a -> Parsec s st a
#

The parser permute perm parses a permutation of parser described by perm. For example, suppose we want to parse a permutation of: an optional string of a's, the character b and an optional c. This can be described by:

 test  = permute (tuple <$?> ("",many1 (char 'a'))
                        <||> char 'b'
                        <|?> ('_',char 'c'))
       where
         tuple a b c  = (a,b,c)
value(<||>)
  1. :: Stream s Identity tok
  2. => StreamPermParser s st (a -> b)
  3. -> Parsec s st a
  4. -> StreamPermParser s st b
#

The expression perm <||> p adds parser p to the permutation parser perm. The parser p is not allowed to accept empty input - use the optional combinator (<|?>) instead. Returns a new permutation parser that includes p.

value(<$$>)
  1. :: Stream s Identity tok
  2. => a -> b
  3. -> Parsec s st a
  4. -> StreamPermParser s st b
#

The expression f <$$> p creates a fresh permutation parser consisting of parser p. The the final result of the permutation parser is the function f applied to the return value of p. The parser p is not allowed to accept empty input - use the optional combinator (<$?>) instead.

If the function f takes more than one parameter, the type variable b is instantiated to a functional type which combines nicely with the adds parser p to the (<||>) combinator. This results in stylized code where a permutation parser starts with a combining function f followed by the parsers. The function f gets its parameters in the order in which the parsers are specified, but actual input can be in any order.

value(<|?>)
  1. :: Stream s Identity tok
  2. => StreamPermParser s st (a -> b)
  3. -> (a, Parsec s st a)
  4. -> StreamPermParser s st b
#

The expression perm <||> (x,p) adds parser p to the permutation parser perm. The parser p is optional - if it can not be applied, the default value x will be used instead. Returns a new permutation parser that includes the optional parser p.

value(<$?>)
  1. :: Stream s Identity tok
  2. => a -> b
  3. -> (a, Parsec s st a)
  4. -> StreamPermParser s st b
#

The expression f <$?> (x,p) creates a fresh permutation parser consisting of parser p. The the final result of the permutation parser is the function f applied to the return value of p. The parser p is optional - if it can not be applied, the default value x will be used instead.