Safe Haskell | None |
---|---|
Language | Haskell2010 |
Combinators for parsing YAML into Haskell types.
Based on the article Better Yaml Parsing.
- data Parser a
- parse :: Parser a -> ByteString -> Either String a
- runParser :: Parser a -> Value -> Either ParseError a
- string :: Parser Text
- theString :: Text -> Parser ()
- number :: Parser Scientific
- integer :: (Integral i, Bounded i) => Parser i
- bool :: Parser Bool
- null_ :: Parser ()
- array :: Parser a -> Parser (Vector a)
- theArray :: ElementParser a -> Parser a
- data ElementParser a
- element :: Parser a -> ElementParser a
- object :: FieldParser a -> Parser a
- data FieldParser a
- field :: Text -> Parser a -> FieldParser a
- optField :: Text -> Parser a -> FieldParser (Maybe a)
- defaultField :: Text -> a -> Parser a -> FieldParser a
- theField :: Text -> Text -> FieldParser ()
- anyValue :: Parser Value
- data ParseError = ParseError !Int Reason
- ppParseError :: ParseError -> String
- data Reason
- validate :: Parser a -> (a -> Either String b) -> Parser b
Documentation
A top-level YAML parser.
parse :: Parser a -> ByteString -> Either String a Source #
Run a Parser
on a ByteString
containing the YAML content.
This is a high-level function implemented on top of runParser
.
Scalars
theString :: Text -> Parser () Source #
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 Source #
Match a real number.
>>>
parse number "3.14159"
Right 3.14159
integer :: (Integral i, Bounded i) => Parser i Source #
Match an integer.
>>>
parse (integer @Int) "2017"
Right 2017
Arrays
array :: Parser a -> Parser (Vector a) Source #
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 Source #
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 Source #
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
withelement
and theApplicative
combinators. - Turn a
FieldParser
into aParser
withtheArray
.
element :: Parser a -> ElementParser a Source #
Construct an ElementParser
that parses the current array element
with the given Parser
.
Objects
object :: FieldParser a -> Parser a Source #
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)
data FieldParser a Source #
A FieldParser
describes how to parse an object.
- Construct a
FieldParser
withfield
,optField
, ortheField
, and theApplicative
combinators. - Turn a
FieldParser
into aParser
withobject
.
:: 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
.
:: 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
.
:: 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.
:: 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)
anyValue :: Parser Value Source #
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 Source #
ppParseError :: ParseError -> String Source #
Pretty-print a ParseError
Since: 1.1
Describes what exactly went wrong during parsing.
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