Data.JustParse

Overview

• Allows for parsing arbitrary Stream types
• Makes extensive use of combinators
• Allows for a parser to return a Partial result
• Returns a list of all possible parses
• Allows for conversion of a regex to a parser

Quickstart Examples

Simple char and string parsing

This parser will only accept the string "hello world"

p = do                
    h <- char 'h'                   --Parses the character 'h'
    rest <- string "ello world"     --Parses the string "ello world"
    ex <- char '!'                  --Parses the character '!'
    return ([h]++rest++[ex])        --Returns all of the above concatenated together
 

Basic combinatorial parsing

This parser will accept the string "hello woooooorld" with any number of o's. It returns the number of o's.

p = do
    string "hello w"         --Parses the string "hello w"
    os <- many1 (char 'o')   --Applies the parser "char 'o'" one or more times
    string "rld"             --Parses the string "rld"
    return (length os)       --Return the number of o's parsed
 

Recursive combinatorial parsing

This parser will turn a string of comma separated values into a list of them. Note that we could use the sepBy parser, but this demonstrates a recursive parser.

csv = do  
    v <- many (noneOf ",")                --Parses as many non-comma characters as possible
    vs <- option [] (char ',' >> csv)     --Optionally parses a comma and a csv, returning the empty list upon failure
    return (v:vs)                         --Concatenates and returns the full list
 

runParser :: Parser s a -> s -> [Result s a]

Supplies the input to the Parser. Returns all Result types, including Partial results.

parseOnly :: Stream s t => Parser s a -> s -> Maybe a

This runs the Parser greedily over the input, finalizes all the results, and returns the first successful result. If there are no successful results, it returns Nothing. This is useful when you are parsing something that you know will have no Partials and you just want an answer.

extend :: (Eq s, Monoid s) => Maybe s -> [Result s a] -> [Result s a]

extend takes a Maybe s as input, and supplies the input to all values in the Result list. For Done values, it appends the Stream to the leftover portion, and for Partial values, it runs the continuation, adding in any new Result values to the output.

finalize :: (Eq s, Monoid s) => [Result s a] -> [Result s a]

finalize takes a list of results (presumably returned from a Parser or Partial, and supplies Nothing to any remaining Partial values, so that only Done values remain.

data Parser s a

Instances

Stream s t => Alternative (Parser s)

Monad (Parser s)

Functor (Parser s)

Stream s t => MonadPlus (Parser s)

Applicative (Parser s)

Stream s t => Monoid (Parser s a)

data Result s a

Constructors

Partial

A Partial wraps the same function as a Parser. Supply it with a Just and it will continue parsing, or with a Nothing and it will terminate.

Fields

continue :: Maybe s -> [Result s a]

Done

A Done contains the resultant value, and the leftover stream, if any.

Fields

value :: a

leftover :: Maybe s

Instances

Functor (Result s)

Show a => Show (Result s a)

class (Eq s, Monoid s) => Stream s t | s -> t where

A Stream instance has a stream of type s, made up of tokens of type t, which must be determinable by the stream. A minimal complete definition only needs to define uncons.

Minimal complete definition

uncons

Methods

uncons :: Stream s t => s -> Maybe (t, s)

uncons returns Nothing if the Stream is empty, otherwise it returns the first token of the stream, followed by the remainder of the stream, wrapped in a Just.

length :: Stream s t => s -> Int

The default length implementation is O(n). If your stream provides a more efficient method for determining the length, it is wise to override this. The length method is only used by the greedy parser.

Instances

Eq t => Stream [t] t

Makes common types such as Strings into a Stream.