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

Copyright | (c) The GHC Team, 1997-2000 (c) Niklas Broberg, 2004-2012
License | BSD-style (see the file LICENSE.txt)
Maintainer | Niklas Broberg, niklas.broberg@chalmers.se
Stability | stable
Portability | portable
Safe Haskell | None
Language | Haskell98

Language.Haskell.Exts.Parser

Contents

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

Description

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])
- data ParseMode = ParseMode {
  - parseFilename :: String
  - baseLanguage :: Language
  - extensions :: [Extension]
  - ignoreLanguagePragmas :: Bool
  - ignoreLinePragmas :: Bool
  - fixities :: Maybe [Fixity]
  - ignoreFunctionArity :: Bool
  }
- defaultParseMode :: ParseMode
- data ParseResult a
  - = ParseOk a
  - | ParseFailed SrcLoc String
- fromParseResult :: ParseResult a -> a
- parseModule :: String -> ParseResult Module
- parseModuleWithMode :: ParseMode -> String -> ParseResult Module
- parseModuleWithComments :: ParseMode -> String -> ParseResult (Module, [Comment])
- parseExp :: String -> ParseResult Exp
- parseExpWithMode :: ParseMode -> String -> ParseResult Exp
- parseExpWithComments :: ParseMode -> String -> ParseResult (Exp, [Comment])
- parseStmt :: String -> ParseResult Stmt
- parseStmtWithMode :: ParseMode -> String -> ParseResult Stmt
- parseStmtWithComments :: ParseMode -> String -> ParseResult (Stmt, [Comment])
- parsePat :: String -> ParseResult Pat
- parsePatWithMode :: ParseMode -> String -> ParseResult Pat
- parsePatWithComments :: ParseMode -> String -> ParseResult (Pat, [Comment])
- parseDecl :: String -> ParseResult Decl
- parseDeclWithMode :: ParseMode -> String -> ParseResult Decl
- parseDeclWithComments :: ParseMode -> String -> ParseResult (Decl, [Comment])
- parseType :: String -> ParseResult Type
- parseTypeWithMode :: ParseMode -> String -> ParseResult Type
- parseTypeWithComments :: ParseMode -> String -> ParseResult (Type, [Comment])
- parseImportDecl :: String -> ParseResult ImportDecl
- parseImportDeclWithMode :: ParseMode -> String -> ParseResult ImportDecl
- parseImportDeclWithComments :: ParseMode -> String -> ParseResult (ImportDecl, [Comment])
- newtype NonGreedy a = NonGreedy {
  - unNonGreedy :: a
  }
- getTopPragmas :: String -> ParseResult [ModulePragma]
- data PragmasAndModuleName = PragmasAndModuleName [ModulePragma] ModuleName
- data PragmasAndModuleHead = PragmasAndModuleHead [ModulePragma] (ModuleName, Maybe WarningText, Maybe [ExportSpec])
- data ModuleHeadAndImports = ModuleHeadAndImports [ModulePragma] (ModuleName, Maybe WarningText, Maybe [ExportSpec]) [ImportDecl]

# 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) |

data ParseMode

Static parameters governing a parse. Note that the various parse functions in Language.Haskell.Exts.Parser never look at LANGUAGE pragmas, regardless of what the `ignoreLanguagePragmas` flag is set to. Only the various `parseFile` functions in Language.Haskell.Exts will act on it, when set to `False`.

Constructors

ParseMode |
Fields parseFilename :: String original name of the file being parsed baseLanguage :: Language base language (e.g. Haskell98, Haskell2010) extensions :: [Extension] list of extensions enabled for parsing ignoreLanguagePragmas :: Bool if `True`, the parser won't care about further extensions in LANGUAGE pragmas in source files ignoreLinePragmas :: Bool if `True`, the parser won't read line position information from LINE pragmas in source files fixities :: Maybe [Fixity] list of fixities to be aware of ignoreFunctionArity :: Bool Checks whether functions have a consistent arity

defaultParseMode :: ParseMode

Default parameters for a parse. The default is an unknown filename, no extensions (i.e. Haskell 98), don't ignore LANGUAGE pragmas, do ignore LINE pragmas, and be aware of fixities from the `Prelude`.

data ParseResult a

The result of a parse.

Constructors

ParseOk a | The parse succeeded, yielding a value.
ParseFailed SrcLoc String | The parse failed at the specified source location, with an error message.

Instances

Monad ParseResult |
Functor ParseResult |
Applicative ParseResult |
Show a => Show (ParseResult a) |
Monoid m => Monoid (ParseResult m) |

fromParseResult :: ParseResult a -> a

Retrieve the result of a successful parse, throwing an error if the parse is actually not successful.

# Parsing of specific AST elements

## Modules

parseModule :: String -> ParseResult Module

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

parseModuleWithMode :: ParseMode -> String -> ParseResult Module

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

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

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

## Expressions

parseExp :: String -> ParseResult Exp

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

parseExpWithMode :: ParseMode -> String -> ParseResult Exp

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

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

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

## Statements

parseStmt :: String -> ParseResult Stmt

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

parseStmtWithMode :: ParseMode -> String -> ParseResult Stmt

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

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

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

## Patterns

parsePat :: String -> ParseResult Pat

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

parsePatWithMode :: ParseMode -> String -> ParseResult Pat

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

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

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

## Declarations

parseDecl :: String -> ParseResult Decl

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

parseDeclWithMode :: ParseMode -> String -> ParseResult Decl

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

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

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

## Types

parseType :: String -> ParseResult Type

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

parseTypeWithMode :: ParseMode -> String -> ParseResult Type

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

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

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

## Import declarations

parseImportDecl :: String -> ParseResult ImportDecl

Parse of a string containing a Haskell import declaration, using `defaultParseMode`.

parseImportDeclWithMode :: ParseMode -> String -> ParseResult ImportDecl

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

parseImportDeclWithComments :: ParseMode -> String -> ParseResult (ImportDecl, [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) |

## Module head parsers

getTopPragmas :: String -> ParseResult [ModulePragma]

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

data PragmasAndModuleName

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 no module name is found (and no parse error occurs), then "Main" is returned. This is the same behavior that `parseModule` has.

Constructors

PragmasAndModuleName [ModulePragma] ModuleName |

Instances

Eq PragmasAndModuleName |
Data PragmasAndModuleName |
Ord PragmasAndModuleName |
Show PragmasAndModuleName |
Parseable (NonGreedy PragmasAndModuleName) |

data PragmasAndModuleHead

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 no module head is found, then a default simple head like "module Main where" is assumed. This is the same behavior that `parseModule` has.

Note that the `ParseMode` particularly matters for this due to the `MagicHash` changing the lexing of identifiers to include "#".

Constructors

PragmasAndModuleHead [ModulePragma] (ModuleName, Maybe WarningText, Maybe [ExportSpec]) |

Instances

Eq PragmasAndModuleHead |
Data PragmasAndModuleHead |
Ord PragmasAndModuleHead |
Show PragmasAndModuleHead |
Parseable (NonGreedy PragmasAndModuleHead) |

data ModuleHeadAndImports

Type intended to be used with `Parseable`, with instances that implement a non-greedy parse of the module head, including top-level pragmas, module name, export list, and import list. This means that if a parse error that comes after the imports won't be returned. If no module head is found, then a default simple head like "module Main where" is assumed. This is the same behavior that `parseModule` has.

Note that the `ParseMode` particularly matters for this due to the `MagicHash` changing the lexing of identifiers to include "#".

Constructors

ModuleHeadAndImports [ModulePragma] (ModuleName, Maybe WarningText, Maybe [ExportSpec]) [ImportDecl] |

Instances

Eq ModuleHeadAndImports |
Data ModuleHeadAndImports |
Ord ModuleHeadAndImports |
Show ModuleHeadAndImports |
Parseable (NonGreedy ModuleHeadAndImports) |