haskell-src-exts-1.17.1: Manipulating Haskell source: abstract syntax, lexer, parser, and pretty-printer

Copyright | (c) Niklas Broberg 2004-2009 (c) Michael Sloan 2013
License | BSD-style (see the file LICENSE.txt)
Maintainer | Niklas Broberg, d00nibro@chalmers.se
Stability | stable
Portability | portable
Safe Haskell | None
Language | Haskell98

Language.Haskell.Exts.Annotated.Parser

Contents

- General parsing
- Parsing of specific AST elements
  - Modules
  - Expressions
  - Statements
  - Patterns
  - Declarations
  - Types
  - Imports
- Non-greedy parsers
  - Module head parsers

Description

Annotated parser for Haskell with extensions.

Synopsis

- class Parseable ast where
  - parse :: String -> ParseResult ast
  - parseWithMode :: ParseMode -> String -> ParseResult ast
  - parseWithComments :: ParseMode -> String -> ParseResult (ast, [Comment])
- parseModule :: String -> ParseResult (Module SrcSpanInfo)
- parseModuleWithMode :: ParseMode -> String -> ParseResult (Module SrcSpanInfo)
- parseModuleWithComments :: ParseMode -> String -> ParseResult (Module SrcSpanInfo, [Comment])
- parseExp :: String -> ParseResult (Exp SrcSpanInfo)
- parseExpWithMode :: ParseMode -> String -> ParseResult (Exp SrcSpanInfo)
- parseExpWithComments :: ParseMode -> String -> ParseResult (Exp SrcSpanInfo, [Comment])
- parseStmt :: String -> ParseResult (Stmt SrcSpanInfo)
- parseStmtWithMode :: ParseMode -> String -> ParseResult (Stmt SrcSpanInfo)
- parseStmtWithComments :: ParseMode -> String -> ParseResult (Stmt SrcSpanInfo, [Comment])
- parsePat :: String -> ParseResult (Pat SrcSpanInfo)
- parsePatWithMode :: ParseMode -> String -> ParseResult (Pat SrcSpanInfo)
- parsePatWithComments :: ParseMode -> String -> ParseResult (Pat SrcSpanInfo, [Comment])
- parseDecl :: String -> ParseResult (Decl SrcSpanInfo)
- parseDeclWithMode :: ParseMode -> String -> ParseResult (Decl SrcSpanInfo)
- parseDeclWithComments :: ParseMode -> String -> ParseResult (Decl SrcSpanInfo, [Comment])
- parseType :: String -> ParseResult (Type SrcSpanInfo)
- parseTypeWithMode :: ParseMode -> String -> ParseResult (Type SrcSpanInfo)
- parseTypeWithComments :: ParseMode -> String -> ParseResult (Type SrcSpanInfo, [Comment])
- parseImportDecl :: String -> ParseResult (ImportDecl SrcSpanInfo)
- parseImportDeclWithMode :: ParseMode -> String -> ParseResult (ImportDecl SrcSpanInfo)
- parseImportDeclWithComments :: ParseMode -> String -> ParseResult (ImportDecl SrcSpanInfo, [Comment])
- newtype NonGreedy a = NonGreedy {
  - unNonGreedy :: a
  }
- data ListOf a = ListOf SrcSpanInfo [a]
- unListOf :: ListOf a -> [a]
- getTopPragmas :: String -> ParseResult [ModulePragma SrcSpanInfo]
- data PragmasAndModuleName l = PragmasAndModuleName l [ModulePragma l] (Maybe (ModuleName l))
- data PragmasAndModuleHead l = PragmasAndModuleHead l [ModulePragma l] (Maybe (ModuleHead l))
- data ModuleHeadAndImports l = ModuleHeadAndImports l [ModulePragma l] (Maybe (ModuleHead l)) [ImportDecl l]

# General parsing

class Parseable ast where

Class providing function for parsing at many different types.

Note that for convenience of implementation, the default methods have definitions equivalent to `undefined`. The minimal definition is all of the visible methods.

Minimal complete definition

parser

Methods

parse :: String -> ParseResult ast

Parse a string with default mode.

parseWithMode :: ParseMode -> String -> ParseResult ast

Parse a string with an explicit `ParseMode`.

parseWithComments :: ParseMode -> String -> ParseResult (ast, [Comment])

Parse a string with an explicit `ParseMode`, returning all comments along with the AST.

Instances

Parseable (NonGreedy (ListOf (ModulePragma SrcSpanInfo))) |
Parseable (NonGreedy (ModuleHeadAndImports SrcSpanInfo)) |
Parseable (NonGreedy (PragmasAndModuleHead SrcSpanInfo)) |
Parseable (NonGreedy (PragmasAndModuleName SrcSpanInfo)) |
Parseable (NonGreedy ModuleHeadAndImports) |
Parseable (NonGreedy PragmasAndModuleHead) |
Parseable (NonGreedy PragmasAndModuleName) |

# Parsing of specific AST elements

## Modules

parseModule :: String -> ParseResult (Module SrcSpanInfo)

Parse of a string, which should contain a complete Haskell module, using `defaultParseMode`.

parseModuleWithMode :: ParseMode -> String -> ParseResult (Module SrcSpanInfo)

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`.

parseModuleWithComments :: ParseMode -> String -> ParseResult (Module SrcSpanInfo, [Comment])

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`, retaining comments.

## Expressions

parseExp :: String -> ParseResult (Exp SrcSpanInfo)

Parse of a string containing a Haskell expression, using `defaultParseMode`.

parseExpWithMode :: ParseMode -> String -> ParseResult (Exp SrcSpanInfo)

Parse of a string containing a Haskell expression, using an explicit `ParseMode`.

parseExpWithComments :: ParseMode -> String -> ParseResult (Exp SrcSpanInfo, [Comment])

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`, retaining comments.

## Statements

parseStmt :: String -> ParseResult (Stmt SrcSpanInfo)

Parse of a string containing a Haskell statement, using `defaultParseMode`.

parseStmtWithMode :: ParseMode -> String -> ParseResult (Stmt SrcSpanInfo)

Parse of a string containing a Haskell type, using an explicit `ParseMode`.

parseStmtWithComments :: ParseMode -> String -> ParseResult (Stmt SrcSpanInfo, [Comment])

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`, retaining comments.

## Patterns

parsePat :: String -> ParseResult (Pat SrcSpanInfo)

Parse of a string containing a Haskell pattern, using `defaultParseMode`.

parsePatWithMode :: ParseMode -> String -> ParseResult (Pat SrcSpanInfo)

Parse of a string containing a Haskell pattern, using an explicit `ParseMode`.

parsePatWithComments :: ParseMode -> String -> ParseResult (Pat SrcSpanInfo, [Comment])

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`, retaining comments.

## Declarations

parseDecl :: String -> ParseResult (Decl SrcSpanInfo)

Parse of a string containing a Haskell top-level declaration, using `defaultParseMode`.

parseDeclWithMode :: ParseMode -> String -> ParseResult (Decl SrcSpanInfo)

Parse of a string containing a Haskell top-level declaration, using an explicit `ParseMode`.

parseDeclWithComments :: ParseMode -> String -> ParseResult (Decl SrcSpanInfo, [Comment])

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`, retaining comments.

## Types

parseType :: String -> ParseResult (Type SrcSpanInfo)

Parse of a string containing a Haskell type, using `defaultParseMode`.

parseTypeWithMode :: ParseMode -> String -> ParseResult (Type SrcSpanInfo)

Parse of a string containing a Haskell type, using an explicit `ParseMode`.

parseTypeWithComments :: ParseMode -> String -> ParseResult (Type SrcSpanInfo, [Comment])

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`, retaining comments.

## Imports

parseImportDecl :: String -> ParseResult (ImportDecl SrcSpanInfo)

Parse of a string containing a Haskell statement, using `defaultParseMode`.

parseImportDeclWithMode :: ParseMode -> String -> ParseResult (ImportDecl SrcSpanInfo)

Parse of a string containing a Haskell type, using an explicit `ParseMode`.

parseImportDeclWithComments :: ParseMode -> String -> ParseResult (ImportDecl SrcSpanInfo, [Comment])

Parse of a string containing a complete Haskell module, using an explicit `ParseMode`, retaining comments.

# Non-greedy parsers

newtype NonGreedy a

Instances of `Parseable` for `NonGreedy a` will only consume the input until `a` is fully parsed. This means that parse errors that come later in the input will be ignored. It's also more efficient, as it's fully lazy in the remainder of the input:

    >>> parse (unlines ("module A where" : "main =" : repeat "blah")) :: ParseResult PragmasAndModuleHead
    ParseOk (NonGreedy {unNonGreedy = PragmasAndModuleHead [] (ModuleName "A",Nothing,Nothing)})

(this example uses the simplified AST)

Constructors

NonGreedy |
Fields unNonGreedy :: a

Instances

Functor NonGreedy |
Eq a => Eq (NonGreedy a) |
Data a => Data (NonGreedy a) |
Ord a => Ord (NonGreedy a) |
Show a => Show (NonGreedy a) |
Parseable (NonGreedy (ListOf (ModulePragma SrcSpanInfo))) |
Parseable (NonGreedy (ModuleHeadAndImports SrcSpanInfo)) |
Parseable (NonGreedy (PragmasAndModuleHead SrcSpanInfo)) |
Parseable (NonGreedy (PragmasAndModuleName SrcSpanInfo)) |
Parseable (NonGreedy ModuleHeadAndImports) |
Parseable (NonGreedy PragmasAndModuleHead) |
Parseable (NonGreedy PragmasAndModuleName) |

data ListOf a

`ListOf a` stores lists of the AST type `a`, along with a `SrcSpanInfo`, in order to provide `Parseable` instances for lists. These instances are provided when the type is used as a list in the syntax, and the same delimiters are used in all of its usages. Some exceptions are made:

Constructors

ListOf SrcSpanInfo [a] |

Instances

Functor ListOf |
Eq a => Eq (ListOf a) |
Data a => Data (ListOf a) |
Ord a => Ord (ListOf a) |
Show a => Show (ListOf a) |
Parseable (NonGreedy (ListOf (ModulePragma SrcSpanInfo))) |

unListOf :: ListOf a -> [a]

## Module head parsers

getTopPragmas :: String -> ParseResult [ModulePragma SrcSpanInfo]

Non-greedy parse of a string starting with a series of top-level option pragmas.

data PragmasAndModuleName l

Type intended to be used with `Parseable`, with instances that implement a non-greedy parse of the module name, including top-level pragmas. This means that a parse error that comes after the module header won't be returned. If the `Maybe` value is `Nothing`, then this means that there was no module header.

Constructors

PragmasAndModuleName l [ModulePragma l] (Maybe (ModuleName l)) |

Instances

Eq l => Eq (PragmasAndModuleName l) |
Data l => Data (PragmasAndModuleName l) |
Ord l => Ord (PragmasAndModuleName l) |
Show l => Show (PragmasAndModuleName l) |
Parseable (NonGreedy (PragmasAndModuleName SrcSpanInfo)) |

data PragmasAndModuleHead l

Constructors

PragmasAndModuleHead l [ModulePragma l] (Maybe (ModuleHead l)) |

Instances

Eq l => Eq (PragmasAndModuleHead l) |
Data l => Data (PragmasAndModuleHead l) |
Ord l => Ord (PragmasAndModuleHead l) |
Show l => Show (PragmasAndModuleHead l) |
Parseable (NonGreedy (PragmasAndModuleHead SrcSpanInfo)) |

data ModuleHeadAndImports l

Constructors

ModuleHeadAndImports l [ModulePragma l] (Maybe (ModuleHead l)) [ImportDecl l] |

Instances

Eq l => Eq (ModuleHeadAndImports l) |
Data l => Data (ModuleHeadAndImports l) |
Ord l => Ord (ModuleHeadAndImports l) |
Show l => Show (ModuleHeadAndImports l) |
Parseable (NonGreedy (ModuleHeadAndImports SrcSpanInfo)) |