Data.Yaml.Combinators

Combinators for parsing YAML into Haskell types.

Based on the article Better Yaml Parsing.

Documentation

data Parser a

A top-level YAML parser.

• Construct a Parser with string, number, integer, bool, array, or object.
• Combine two or more Parsers with Monoid or Semigroup operators such as mappend, <>, or mconcat — e.g. if you expect either an object or a string.
• Run with parse or runParser.

Instances

Functor Parser

Defined in Data.Yaml.Combinators

Methods

fmap :: (a -> b) -> Parser a -> Parser b

(<$) :: a -> Parser b -> Parser a

Semigroup (Parser a)

Defined in Data.Yaml.Combinators

Methods

(<>) :: Parser a -> Parser a -> Parser a

sconcat :: NonEmpty (Parser a) -> Parser a

stimes :: Integral b => b -> Parser a -> Parser a

Monoid (Parser a)

Defined in Data.Yaml.Combinators

Methods

mempty :: Parser a

mappend :: Parser a -> Parser a -> Parser a

mconcat :: [Parser a] -> Parser a

parse :: Parser a -> ByteString -> Either String a

Run a Parser on a ByteString containing the YAML content.

This is a high-level function implemented on top of runParser.

runParser :: Parser a -> Value -> Either ParseError a

A low-level function to run a Parser.

Scalars

string :: Parser Text

Match a single YAML string.

>>> parse string "howdy"
Right "howdy"

theString :: Text -> Parser ()

Match a specific YAML string, usually a «tag» identifying a particular form of an array or object.

>>> parse (theString "hello") "hello"
Right ()
>>> either putStr print $ parse (theString "hello") "bye"
Expected "hello" instead of:

bye

number :: Parser Scientific

Match a real number.

>>> parse number "3.14159"
Right 3.14159

integer :: (Integral i, Bounded i) => Parser i

Match an integer.

>>> parse (integer @Int) "2017"
Right 2017

bool :: Parser Bool

Match a boolean.

>>> parse bool "yes"
Right True

null_ :: Parser ()

Match the null value.

>>> parse null_ "null"
Right ()

Since: 1.1

Arrays

array :: Parser a -> Parser (Vector a)

Match an array of elements, where each of elements are matched by the same parser. This is the function you'll use most of the time when parsing arrays, as they are usually homogeneous.

>>> parse (array string) "[a,b,c]"
Right ["a","b","c"]

theArray :: ElementParser a -> Parser a

Match an array consisting of a fixed number of elements. The way each element is parsed depends on its position within the array and is determined by the ElementParser.

>>> parse (theArray $ (,) <$> element string <*> element bool) "[f, true]"
Right ("f",True)

data ElementParser a

An ElementParser describes how to parse a fixed-size array where each positional element has its own parser.

This can be used to parse heterogeneous tuples represented as YAML arrays.

• Construct an ElementParser with element and the Applicative combinators.
• Turn a FieldParser into a Parser with theArray.

Instances

Functor ElementParser

Defined in Data.Yaml.Combinators

Methods

fmap :: (a -> b) -> ElementParser a -> ElementParser b

(<$) :: a -> ElementParser b -> ElementParser a

Applicative ElementParser

Defined in Data.Yaml.Combinators

Methods

pure :: a -> ElementParser a

(<*>) :: ElementParser (a -> b) -> ElementParser a -> ElementParser b

liftA2 :: (a -> b -> c) -> ElementParser a -> ElementParser b -> ElementParser c

(*>) :: ElementParser a -> ElementParser b -> ElementParser b

(<*) :: ElementParser a -> ElementParser b -> ElementParser a

element :: Parser a -> ElementParser a

Construct an ElementParser that parses the current array element with the given Parser.

Objects

object :: FieldParser a -> Parser a

Match an object. Which set of keys to expect and how their values should be parsed is determined by the FieldParser.

>>> let p = object $ (,) <$> field "name" string <*> optField "age" (integer @Int)
>>> parse p "{ name: Anton, age: 2 }"
Right ("Anton",Just 2)
>>> parse p "name: Roma"
Right ("Roma",Nothing)

By default, this function will fail when there are unrecognized fields in the object. See extraFields for a way to capture or ignore them.

data FieldParser a

A FieldParser describes how to parse an object.

• Construct a FieldParser with field, optField, or theField, and the Applicative combinators.
• Turn a FieldParser into a Parser with object.

Instances

Functor FieldParser

Defined in Data.Yaml.Combinators

Methods

fmap :: (a -> b) -> FieldParser a -> FieldParser b

(<$) :: a -> FieldParser b -> FieldParser a

Applicative FieldParser

Defined in Data.Yaml.Combinators

Methods

pure :: a -> FieldParser a

(<*>) :: FieldParser (a -> b) -> FieldParser a -> FieldParser b

liftA2 :: (a -> b -> c) -> FieldParser a -> FieldParser b -> FieldParser c

(*>) :: FieldParser a -> FieldParser b -> FieldParser b

(<*) :: FieldParser a -> FieldParser b -> FieldParser a

field

Arguments

:: Text

field name

-> Parser a

value parser

-> FieldParser a

Require an object field with the given name and with a value matched by the given Parser.

optField

Arguments

:: Text

field name

-> Parser a

value parser

-> FieldParser (Maybe a)

Declare an optional object field with the given name and with a value matched by the given Parser.

defaultField

Arguments

:: Text

field name

-> a

default value

-> Parser a

value parser

-> FieldParser a

Declare an optional object field with the given name and with a default to use if the field is absent.

theField

Arguments

:: Text

key name

-> Text

expected value

-> FieldParser ()

Require an object field with the given name and the given string value.

This is a convenient wrapper around theString intended for «tagging» objects.

>>> :{
    let p = object (Right <$ theField "type" "number" <*> field "value" number)
         <> object (Left  <$ theField "type" "string" <*> field "value" string)
>>> :}

>>> parse p "{type: string, value: abc}"
Right (Left "abc")
>>> parse p "{type: number, value: 123}"
Right (Right 123.0)

extraFields :: FieldParser Object

This combinator does two things:

1. Allow extra fields (not specified by field, theField etc.) in the parsed object.
2. Return such extra fields as an Value.

The return value can be of course ignored.

>>> let fp = field "name" string
>>> either putStr print $ parse (object fp) "name: Anton"
"Anton"
>>> either putStr print $ parse (object fp) "{name: Anton, age: 2}"
Unexpected

age: 2

as part of

age: 2
name: Anton
>>> either putStr print $ parse (object $ (,) <$> fp <*> extraFields) "{name: Anton, age: 2}"
("Anton",fromList [("age",Number 2.0)])
>>> either putStr print $ parse (object $ fp <* extraFields) "{name: Anton, age: 2}"
"Anton"

Since: 1.1.2

Arbitrary values

anyValue :: Parser Value

Match any JSON value and return it as Aeson's Value.

>>> parse anyValue "[one, two, {three: four}]"
Right (Array [String "one",String "two",Object (fromList [("three",String "four")])])

Since: 1.1.1

Errors

data ParseError

A parse error. Reason describes the error. The Int field denotes at which level the error occurred and is used to select the deepest (most relevant) error when merging multiple parsers.

Constructors

ParseError !Int Reason

Instances

Eq ParseError

Defined in Data.Yaml.Combinators

Methods

(==) :: ParseError -> ParseError -> Bool

(/=) :: ParseError -> ParseError -> Bool

Show ParseError

Defined in Data.Yaml.Combinators

Methods

showsPrec :: Int -> ParseError -> ShowS

show :: ParseError -> String

showList :: [ParseError] -> ShowS

ppParseError :: ParseError -> String

Pretty-print a ParseError

Since: 1.1

data Reason

Describes what exactly went wrong during parsing.

Constructors

UnexpectedAsPartOf Value Value

ExpectedAsPartOf (HashSet String) Value

ExpectedInsteadOf (HashSet String) Value

Instances

Eq Reason

Defined in Data.Yaml.Combinators

Methods

(==) :: Reason -> Reason -> Bool

(/=) :: Reason -> Reason -> Bool

Show Reason

Defined in Data.Yaml.Combinators

Methods

showsPrec :: Int -> Reason -> ShowS

show :: Reason -> String

showList :: [Reason] -> ShowS

validate

Arguments

:: Parser a

parser to wrap

-> (a -> Either String b)

validator

-> Parser b

Make a parser match only valid values.

If the validator does not accept the value, it should return a Left String with a noun phrase that characterizes the expected value, as in the example:

>>> let acceptEven n = if even n then Right n else Left "an even number"
>>> either putStr print $ parse (integer @Int `validate` acceptEven) "2017"
Expected an even number instead of:

2017

Since: 1.0.1

Orphan instances

Generic Value

Associated Types

type Code Value :: [[Type]]

Methods

from :: Value -> Rep Value

to :: Rep Value -> Value

HasDatatypeInfo Value

Associated Types

type DatatypeInfoOf Value :: DatatypeInfo

Methods

datatypeInfo :: proxy Value -> DatatypeInfo (Code Value)