Types that can be parsed from a node. A type with a Generic instance can derive the instance via GenericYaml.

An instance for a record reads a mapping with withMapping:

>>> :{
data Server = Server {host :: T.Text, port :: Int, tags :: [T.Text]}
  deriving stock (Show)
instance FromYaml Server where
  parseYaml = withMapping $ \o ->
    rejectUnknownKeys ["host", "port", "tags"] o
      *> ( Server
             <$> parseField o "host"
             <*> parseFieldDefault o "port" 80
             <*> parseFieldDefault o "tags" []
         )
:}

>>> decodeText @Server "host: example.com\ntags:\n- web\n"
Right (Server {host = "example.com", port = 80, tags = ["web"]})

The decoder reports the errors of all fields together:

>>> either printErrors print (decodeText @Server "hots: example.com\nport: http\n")
input.yaml:1:1: unknown key "hots", did you mean "host"?
  |
1 | hots: example.com
  | ^
input.yaml:1:1: missing key "host"
  |
1 | hots: example.com
  | ^
input.yaml:2:7: port: expected an integer, but got a string
  |
2 | port: http
  |       ^

The instances of the library copy the texts that they keep, so a decoded value does not keep the input in memory. A value from a hand-written instance can keep the input while it has unevaluated parts, e.g. a lazy list. Evaluate such a value, e.g. with force, to release the input.

A parser of nodes. Its errors point to the node that the parser works on, unless failAt names another one.

The parser has no Alternative instance. To try another parser after a failure, use orElse. To reject a value, fail with a message that says why:

port <- parseYaml n
unless (port > 0 && port < 65536) $ fail "the port must be from 1 to 65535"

The applicative operators collect the errors of both parts: <*>, *>, <*, liftA2, and the functions that use them, e.g. traverse, mapM on a list and for_. This parser gives the errors of the unknown keys and of all fields together:

rejectUnknownKeys ["name", "paths"] o
  *> (Config <$> parseField o "name" <*> parseField o "paths")

>>= and >> stop at the first error. A statement of a do block also stops, e.g. the check of the port above. The functions that use >> also stop, e.g. mapM_ and forM_.

The choice between them changes only the errors, never the result. With ApplicativeDo, GHC turns the independent statements of a do block that ends with pure into <*>. Then they collect errors.

Run a parser on a node. Each error is the offset of the node that caused it and the message. The errors are in the order of the offsets, and equal errors come only once. A note on an error comes right after it, e.g. the first key of a duplicate key.

First, the function makes the checks of decodeDocument on the node, e.g. for duplicate keys. It also replaces each alias with the node that the alias refers to. If a check fails, the result has only the error of that check, with its notes.

Run a parser on a node, so that fail points to the node.

Fail with an error that points to the given node.

Fail with an error that the node is not of the expected kind, e.g. typeMismatch "a list" n gives "expected a list, but got a string".

Run the second parser if the first one fails. A port can be a number or a name:

>>> :{
newtype Port = Port (Either Integer T.Text)
  deriving stock (Show)
instance FromYaml Port where
  parseYaml n =
    Port <$> ((Left <$> withInt pure n) `orElse` (Right <$> withText pure n))
:}

>>> decodeText @Port "8080"
Right (Port (Left 8080))

>>> decodeText @Port "http"
Right (Port (Right "http"))

If both parsers fail, the result has only the errors of the second one:

>>> either printErrors print (decodeText @Port "[80]")
input.yaml:1:1: expected a string, but got a list
  |
1 | [80]
  | ^

The value of a node with its tag resolved. The items and the entries of a collection stay nodes of the syntax tree. A tag that the schema does not know does not matter, e.g. !secret abc is a string.

The view of a node.

The kind of a node in plain words, e.g. "a list".

>>> map describeNode <$> decodeText @[Node] "- [1, 2]\n- 3.5\n- ~\n- !!str 12\n"
Right ["a list","a floating-point number","null","a string"]

Run the parser if the node is null.

The value of a boolean.

The value of an integer.

The nearest double. An integer counts as a floating-point number too.

The exact value of a finite number. An integer counts too, and negative zero becomes 0.

A conversion to an exact type, e.g. with truncate, is safe for untrusted input. An integer has the digits of its text, and the decoder rejects a float whose exponent in scientific notation is beyond the range from -1000 to 1000, also in a node that a program built.

The text of a string. The text is a copy, so it does not keep the input alive. For a plain scalar that YAML reads as a number or a boolean, e.g. 3.10, the error suggests quotes.

The value that goes with the string in the list of pairs, e.g. for names that the program knows only at run time. An empty list rejects every value. The errors are the same as for the constructors of an enumeration. An unknown name gets the closest name or the list of names:

>>> :{
newtype Size = Size Int
  deriving stock (Show)
instance FromYaml Size where
  parseYaml = oneOf [("small", Size 1), ("large", Size 2)]
:}

>>> decodeText @Size "large"
Right (Size 2)

>>> either printErrors print (decodeText @Size "lage")
input.yaml:1:1: unknown value "lage", did you mean "large"?
  |
1 | lage
  | ^

The items of a sequence. As for withMapping, the comments of the sequence stay with it, not with its first item.

The values of the items, with the errors of all items, as with mapM. Unlike mapM, the stack does not grow with the number of items, because the errors and the values are in accumulators until the end. A decoder of a list is withSequence (parseItems parseYaml).

The entries of a mapping. As for withText, the tag of a string key does not matter, so two string keys with the same text are an error, e.g. a and !foo a.

The comments of the mapping stay with it, not with its first key, e.g. a comment at the top of a file. A record has no place for them.

A mapping with fast access to the values of string keys.

The node of the mapping.

The entries of the mapping in the order of the input.

The string keys of the mapping in the order of the input.

The value of a key, or Nothing if the key is missing. As for parseField, a key with the same text that is not a string, e.g. 404, is an error, so that its value does not go away.

The value of a key. It is an error if the key is missing.

The value of a key, or Nothing if the key is missing or its value is null.

The value of a key, or Nothing if the key is missing. Unlike parseFieldMaybe, a null value goes to the parser of the value, e.g. Maybe a gives Just Nothing for a null value.

>>> :{
newtype Limit = Limit (Maybe (Maybe Int))
  deriving stock (Show)
instance FromYaml Limit where
  parseYaml = withMapping $ \o -> Limit <$> parseFieldIfPresent o "limit"
:}

>>> decodeText @Limit "limit: null\n"
Right (Limit (Just Nothing))

>>> decodeText @Limit "{}"
Right (Limit Nothing)

The value of a key, or the default if the key is missing or its value is null.

>>> :{
newtype Server = Server Int
  deriving stock (Show)
instance FromYaml Server where
  parseYaml = withMapping $ \o -> Server <$> parseFieldDefault o "port" 80
:}

>>> decodeText @Server "{}"
Right (Server 80)

>>> decodeText @Server "port: null\n"
Right (Server 80)

>>> decodeText @Server "port: 8080\n"
Right (Server 8080)

Like parseField, with the given parser for the value, e.g. to check a value without a new type for it. The errors of the parser point to the value. The parser gets only the value, so it cannot keep the comments of the key, as a Commented field does with parseField.

>>> :{
newtype Port = Port Int
  deriving stock (Show)
instance FromYaml Port where
  parseYaml = withMapping $ \o -> Port <$> parseFieldWith number o "port"
    where
      number :: Node -> Parser Int
      number = withInt $ \i ->
        if i >= 1 && i <= 65535
          then pure (fromInteger i)
          else fail "expected a port from 1 to 65535"
:}

>>> decodeText @Port "port: 80\n"
Right (Port 80)

>>> either printErrors print (decodeText @Port "port: 70000\n")
input.yaml:1:7: port: expected a port from 1 to 65535
  |
1 | port: 70000
  |       ^

Like parseFieldMaybe, with the given parser for the value, as in parseFieldWith. The result is Nothing if the key is missing or its value is null. The parser never gets a null value, so a missing key and a null value mean the same.

>>> :{
newtype Job = Job (Maybe Int)
  deriving stock (Show)
instance FromYaml Job where
  parseYaml = withMapping $ \o -> Job <$> parseFieldMaybeWith positive o "retries"
    where
      positive :: Node -> Parser Int
      positive = withInt $ \i ->
        if i > 0 then pure (fromInteger i) else fail "expected a positive number"
:}

>>> decodeText @Job "{}"
Right (Job Nothing)

>>> decodeText @Job "retries: null\n"
Right (Job Nothing)

>>> decodeText @Job "retries: 3\n"
Right (Job (Just 3))

To give a null value to the parser, use parseFieldIfPresentWith.

Like parseFieldIfPresent, with the given parser for the value, as in parseFieldWith. The result is Nothing only if the key is missing. A null value goes to the parser, so the parser can give it a meaning of its own. Here a missing key takes the default limit, and null means no limit:

>>> :{
data Limit = Unlimited | Limit Int
  deriving stock (Show)
newtype Job = Job (Maybe Limit)
  deriving stock (Show)
instance FromYaml Job where
  parseYaml = withMapping $ \o -> Job <$> parseFieldIfPresentWith limit o "limit"
    where
      limit :: Node -> Parser Limit
      limit n = case view n of
        NullView -> pure Unlimited
        _ -> withInt (pure . Limit . fromInteger) n
:}

>>> decodeText @Job "{}"
Right (Job Nothing)

>>> decodeText @Job "limit: null\n"
Right (Job (Just Unlimited))

>>> decodeText @Job "limit: 3\n"
Right (Job (Just (Limit 3)))

With parseFieldMaybeWith, the null value would give Nothing, the same as the missing key.

Like parseFieldDefault, with the given parser for the value, as in parseFieldWith. The parser never gets a null value.

>>> :{
newtype Job = Job Int
  deriving stock (Show)
instance FromYaml Job where
  parseYaml = withMapping $ \o -> Job <$> parseFieldDefaultWith positive o "retries" 1
    where
      positive :: Node -> Parser Int
      positive = withInt $ \i ->
        if i > 0 then pure (fromInteger i) else fail "expected a positive number"
:}

>>> decodeText @Job "{}"
Right (Job 1)

>>> decodeText @Job "retries: 3\n"
Right (Job 3)

Fail at each key that is not in the list. If a key in the list is close to an unknown key, e.g. "host" to "hots", its error suggests it. Otherwise the error lists the known keys. An empty list accepts only an empty mapping, e.g. for a value written as {}.

A key that is not a string, but has the text of a known key, e.g. true, is left to the lookup of that key, e.g. parseField or lookupKey, which reports it.