Safe Haskell	None
Language	Haskell2010

Data.Yaml

Contents

Encoding
Decoding
- Decoding multiple documents
- More control over decoding
Types
Constructors and accessors
- With helpers (since 0.8.23)
Parsing
Classes
Custom encoding
Deprecated

Description

Provides a high-level interface for processing YAML files.

This module reuses most of the infrastructure from the aeson package. This means that you can use all of the existing tools for JSON processing for processing YAML files. As a result, much of the documentation below mentions JSON; do not let that confuse you, it's intentional.

For the most part, YAML content translates directly into JSON, and therefore there is very little data loss. If you need to deal with YAML more directly (e.g., directly deal with aliases), you should use the Text.Libyaml module instead.

For documentation on the aeson types, functions, classes, and operators, please see the Data.Aeson module of the aeson package.

Look in the examples directory of the source repository for some initial pointers on how to use this library.

Synopsis

encode :: ToJSON a => a -> ByteString
encodeWith :: ToJSON a => EncodeOptions -> a -> ByteString
encodeFile :: ToJSON a => FilePath -> a -> IO ()
encodeFileWith :: ToJSON a => EncodeOptions -> FilePath -> a -> IO ()
decodeEither' :: FromJSON a => ByteString -> Either ParseException a
decodeFileEither :: FromJSON a => FilePath -> IO (Either ParseException a)
decodeFileWithWarnings :: FromJSON a => FilePath -> IO (Either ParseException ([Warning], a))
decodeThrow :: (MonadThrow m, FromJSON a) => ByteString -> m a
decodeFileThrow :: (MonadIO m, FromJSON a) => FilePath -> m a
decodeAllEither' :: FromJSON a => ByteString -> Either ParseException [a]
decodeAllFileEither :: FromJSON a => FilePath -> IO (Either ParseException [a])
decodeAllFileWithWarnings :: FromJSON a => FilePath -> IO (Either ParseException ([Warning], [a]))
decodeAllThrow :: (MonadThrow m, FromJSON a) => ByteString -> m [a]
decodeAllFileThrow :: (MonadIO m, FromJSON a) => FilePath -> m [a]
decodeHelper :: FromJSON a => ConduitM () Event Parse () -> IO (Either ParseException ([Warning], Either String a))
data Value
- = Object !Object
- | Array !Array
- | String !Text
- | Number !Scientific
- | Bool !Bool
- | Null
data Parser a
type Object = KeyMap Value
type Array = Vector Value
data ParseException
- = NonScalarKey
- | UnknownAlias {
  - _anchorName :: AnchorName
  }
- | UnexpectedEvent {
  - _received :: Maybe Event
  - _expected :: Maybe Event
  }
- | InvalidYaml (Maybe YamlException)
- | MultipleDocuments
- | AesonException String
- | OtherParseException SomeException
- | NonStringKey JSONPath
- | NonStringKeyAlias AnchorName Value
- | CyclicIncludes
- | LoadSettingsException FilePath ParseException
prettyPrintParseException :: ParseException -> String
data YamlException
- = YamlException String
- | YamlParseException {
  - yamlProblem :: String
  - yamlContext :: String
  - yamlProblemMark :: YamlMark
  }
data YamlMark = YamlMark {
- yamlIndex :: Int
- yamlLine :: Int
- yamlColumn :: Int
}
object :: [Pair] -> Value
array :: [Value] -> Value
(.=) :: (KeyValue e kv, ToJSON v) => Key -> v -> kv
(.:) :: FromJSON a => Object -> Key -> Parser a
(.:?) :: FromJSON a => Object -> Key -> Parser (Maybe a)
(.!=) :: Parser (Maybe a) -> a -> Parser a
withObject :: String -> (Object -> Parser a) -> Value -> Parser a
withText :: String -> (Text -> Parser a) -> Value -> Parser a
withArray :: String -> (Array -> Parser a) -> Value -> Parser a
withScientific :: String -> (Scientific -> Parser a) -> Value -> Parser a
withBool :: String -> (Bool -> Parser a) -> Value -> Parser a
parseMonad :: MonadFail m => (a -> Parser b) -> a -> m b
parseEither :: (a -> Parser b) -> a -> Either String b
parseMaybe :: (a -> Parser b) -> a -> Maybe b
class ToJSON a where
- toJSON :: a -> Value
- toEncoding :: a -> Encoding
- toJSONList :: [a] -> Value
- toEncodingList :: [a] -> Encoding
- omitField :: a -> Bool
class FromJSON a where
- parseJSON :: Value -> Parser a
- parseJSONList :: Value -> Parser [a]
- omittedField :: Maybe a
isSpecialString :: Text -> Bool
data EncodeOptions
defaultEncodeOptions :: EncodeOptions
defaultStringStyle :: StringStyle
setStringStyle :: (Text -> (Tag, Style)) -> EncodeOptions -> EncodeOptions
setFormat :: FormatOptions -> EncodeOptions -> EncodeOptions
data FormatOptions
defaultFormatOptions :: FormatOptions
setWidth :: Maybe Int -> FormatOptions -> FormatOptions
decode :: FromJSON a => ByteString -> Maybe a
decodeFile :: FromJSON a => FilePath -> IO (Maybe a)
decodeEither :: FromJSON a => ByteString -> Either String a

Encoding

encode :: ToJSON a => a -> ByteString Source #

Encode a value into its YAML representation.

encodeWith :: ToJSON a => EncodeOptions -> a -> ByteString Source #

Encode a value into its YAML representation with custom styling.

Since: 0.10.2.0

encodeFile :: ToJSON a => FilePath -> a -> IO () Source #

Encode a value into its YAML representation and save to the given file.

encodeFileWith :: ToJSON a => EncodeOptions -> FilePath -> a -> IO () Source #

Encode a value into its YAML representation with custom styling and save to the given file.

Since: 0.10.2.0

Decoding

decodeEither' :: FromJSON a => ByteString -> Either ParseException a Source #

More helpful version of decodeEither which returns the YamlException.

Since: 0.8.3

decodeFileEither :: FromJSON a => FilePath -> IO (Either ParseException a) Source #

A version of decodeFile which should not throw runtime exceptions.

Since: 0.8.4

decodeFileWithWarnings :: FromJSON a => FilePath -> IO (Either ParseException ([Warning], a)) Source #

A version of decodeFileEither that returns warnings along with the parse result.

Since: 0.10.0

decodeThrow :: (MonadThrow m, FromJSON a) => ByteString -> m a Source #

A version of decodeEither' lifted to MonadThrow

Since: 0.8.31

decodeFileThrow :: (MonadIO m, FromJSON a) => FilePath -> m a Source #

A version of decodeFileEither lifted to MonadIO

Since: 0.8.31

Decoding multiple documents

For situations where we need to be able to parse multiple documents separated by `---` in a YAML stream, these functions decode a list of values rather than a single value.

decodeAllEither' :: FromJSON a => ByteString -> Either ParseException [a] Source #

Like decodeEither', but decode multiple documents.

Since: 0.11.5.0

decodeAllFileEither :: FromJSON a => FilePath -> IO (Either ParseException [a]) Source #

Like decodeFileEither, but decode multiple documents.

Since: 0.11.5.0

decodeAllFileWithWarnings :: FromJSON a => FilePath -> IO (Either ParseException ([Warning], [a])) Source #

Like decodeFileWithWarnings, but decode multiple documents.

Since: 0.11.5.0

decodeAllThrow :: (MonadThrow m, FromJSON a) => ByteString -> m [a] Source #

Like decodeThrow, but decode multiple documents.

Since: 0.11.5.0

decodeAllFileThrow :: (MonadIO m, FromJSON a) => FilePath -> m [a] Source #

Like decodeFileThrow, but decode multiple documents.

Since: 0.11.5.0

More control over decoding

decodeHelper :: FromJSON a => ConduitM () Event Parse () -> IO (Either ParseException ([Warning], Either String a)) Source #

Types

data Value #

Constructors

Object !Object
Array !Array
String !Text
Number !Scientific
Bool !Bool
Null

Instances

Instances details

Arbitrary Value #

Instance details

Defined in Data.Aeson.Types.Internal

Methods

arbitrary :: Gen Value

shrink :: Value -> [Value]

CoArbitrary Value #

Instance details

Defined in Data.Aeson.Types.Internal

Methods

coarbitrary :: Value -> Gen b -> Gen b

Function Value #

Instance details

Defined in Data.Aeson.Types.Internal

Methods

function :: (Value -> b) -> Value :-> b

FromJSON Value #

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser Value #

parseJSONList :: Value -> Parser [Value] #

omittedField :: Maybe Value #

ToJSON Value #

Instance details

Alternative Parser #
Instance details Defined in Data.Aeson.Types.Internal Methods empty :: Parser a # (<\|>) :: Parser a -> Parser a -> Parser a # some :: Parser a -> Parser [a] # many :: Parser a -> Parser [a] #
Applicative Parser #
Instance details Defined in Data.Aeson.Types.Internal Methods pure :: a -> Parser a # (<>) :: Parser (a -> b) -> Parser a -> Parser b # liftA2 :: (a -> b -> c) -> Parser a -> Parser b -> Parser c # (>) :: Parser a -> Parser b -> Parser b # (<*) :: Parser a -> Parser b -> Parser a #
Functor Parser #
Instance details Defined in Data.Aeson.Types.Internal Methods fmap :: (a -> b) -> Parser a -> Parser b # (<$) :: a -> Parser b -> Parser a #
Monad Parser #
Instance details Defined in Data.Aeson.Types.Internal Methods (>>=) :: Parser a -> (a -> Parser b) -> Parser b # (>>) :: Parser a -> Parser b -> Parser b # return :: a -> Parser a #
MonadPlus Parser #
Instance details Defined in Data.Aeson.Types.Internal Methods mzero :: Parser a # mplus :: Parser a -> Parser a -> Parser a #
MonadFail Parser #
Instance details Defined in Data.Aeson.Types.Internal Methods fail :: HasCallStack => String -> Parser a #
MonadFix Parser #
Instance details Defined in Data.Aeson.Types.Internal Methods mfix :: (a -> Parser a) -> Parser a #
Monoid (Parser a) #
Instance details Defined in Data.Aeson.Types.Internal Methods mempty :: Parser a # mappend :: Parser a -> Parser a -> Parser a # mconcat :: [Parser a] -> Parser a #
Semigroup (Parser a) #
Instance details Defined in Data.Aeson.Types.Internal Methods (<>) :: Parser a -> Parser a -> Parser a # sconcat :: NonEmpty (Parser a) -> Parser a # stimes :: Integral b => b -> Parser a -> Parser a #

NonScalarKey
UnknownAlias
Fields _anchorName :: AnchorName
UnexpectedEvent
Fields _received :: Maybe Event _expected :: Maybe Event
InvalidYaml (Maybe YamlException)
MultipleDocuments
AesonException String
OtherParseException SomeException
NonStringKey JSONPath
NonStringKeyAlias AnchorName Value
CyclicIncludes
LoadSettingsException FilePath ParseException

Exception ParseException Source #
Instance details Defined in Data.Yaml.Internal Methods toException :: ParseException -> SomeException # fromException :: SomeException -> Maybe ParseException # displayException :: ParseException -> String # backtraceDesired :: ParseException -> Bool #
Show ParseException Source #
Instance details Defined in Data.Yaml.Internal Methods showsPrec :: Int -> ParseException -> ShowS # show :: ParseException -> String # showList :: [ParseException] -> ShowS #

YamlException String
YamlParseException
Fields yamlProblem :: String yamlContext :: String yamlProblemMark :: YamlMark

Exception YamlException #
Instance details Defined in Text.Libyaml Methods toException :: YamlException -> SomeException # fromException :: SomeException -> Maybe YamlException # displayException :: YamlException -> String # backtraceDesired :: YamlException -> Bool #
Show YamlException #
Instance details Defined in Text.Libyaml Methods showsPrec :: Int -> YamlException -> ShowS # show :: YamlException -> String # showList :: [YamlException] -> ShowS #

YamlMark
Fields yamlIndex :: Int yamlLine :: Int yamlColumn :: Int

Show YamlMark #
Instance details Defined in Text.Libyaml Methods showsPrec :: Int -> YamlMark -> ShowS # show :: YamlMark -> String # showList :: [YamlMark] -> ShowS #

ToJSON Key #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Key -> Value # toEncoding :: Key -> Encoding # toJSONList :: [Key] -> Value # toEncodingList :: [Key] -> Encoding # omitField :: Key -> Bool #
ToJSON DotNetTime #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: DotNetTime -> Value # toEncoding :: DotNetTime -> Encoding # toJSONList :: [DotNetTime] -> Value # toEncodingList :: [DotNetTime] -> Encoding # omitField :: DotNetTime -> Bool #
ToJSON Value #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Value -> Value # toEncoding :: Value -> Encoding # toJSONList :: [Value] -> Value # toEncodingList :: [Value] -> Encoding # omitField :: Value -> Bool #
ToJSON IntSet #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: IntSet -> Value # toEncoding :: IntSet -> Encoding # toJSONList :: [IntSet] -> Value # toEncodingList :: [IntSet] -> Encoding # omitField :: IntSet -> Bool #
ToJSON Void #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Void -> Value # toEncoding :: Void -> Encoding # toJSONList :: [Void] -> Value # toEncodingList :: [Void] -> Encoding # omitField :: Void -> Bool #
ToJSON All #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: All -> Value # toEncoding :: All -> Encoding # toJSONList :: [All] -> Value # toEncodingList :: [All] -> Encoding # omitField :: All -> Bool #
ToJSON Any #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Any -> Value # toEncoding :: Any -> Encoding # toJSONList :: [Any] -> Value # toEncodingList :: [Any] -> Encoding # omitField :: Any -> Bool #
ToJSON Version #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Version -> Value # toEncoding :: Version -> Encoding # toJSONList :: [Version] -> Value # toEncodingList :: [Version] -> Encoding # omitField :: Version -> Bool #
ToJSON CTime #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: CTime -> Value # toEncoding :: CTime -> Encoding # toJSONList :: [CTime] -> Value # toEncodingList :: [CTime] -> Encoding # omitField :: CTime -> Bool #
ToJSON Int16 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Int16 -> Value # toEncoding :: Int16 -> Encoding # toJSONList :: [Int16] -> Value # toEncodingList :: [Int16] -> Encoding # omitField :: Int16 -> Bool #
ToJSON Int32 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Int32 -> Value # toEncoding :: Int32 -> Encoding # toJSONList :: [Int32] -> Value # toEncodingList :: [Int32] -> Encoding # omitField :: Int32 -> Bool #
ToJSON Int64 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Int64 -> Value # toEncoding :: Int64 -> Encoding # toJSONList :: [Int64] -> Value # toEncodingList :: [Int64] -> Encoding # omitField :: Int64 -> Bool #
ToJSON Int8 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Int8 -> Value # toEncoding :: Int8 -> Encoding # toJSONList :: [Int8] -> Value # toEncodingList :: [Int8] -> Encoding # omitField :: Int8 -> Bool #
ToJSON Ordering #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Ordering -> Value # toEncoding :: Ordering -> Encoding # toJSONList :: [Ordering] -> Value # toEncodingList :: [Ordering] -> Encoding # omitField :: Ordering -> Bool #
ToJSON Word16 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Word16 -> Value # toEncoding :: Word16 -> Encoding # toJSONList :: [Word16] -> Value # toEncodingList :: [Word16] -> Encoding # omitField :: Word16 -> Bool #
ToJSON Word32 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Word32 -> Value # toEncoding :: Word32 -> Encoding # toJSONList :: [Word32] -> Value # toEncodingList :: [Word32] -> Encoding # omitField :: Word32 -> Bool #
ToJSON Word64 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Word64 -> Value # toEncoding :: Word64 -> Encoding # toJSONList :: [Word64] -> Value # toEncodingList :: [Word64] -> Encoding # omitField :: Word64 -> Bool #
ToJSON Word8 #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Word8 -> Value # toEncoding :: Word8 -> Encoding # toJSONList :: [Word8] -> Value # toEncodingList :: [Word8] -> Encoding # omitField :: Word8 -> Bool #
ToJSON URI #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: URI -> Value # toEncoding :: URI -> Encoding # toJSONList :: [URI] -> Value # toEncodingList :: [URI] -> Encoding # omitField :: URI -> Bool #
ToJSON Scientific #
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Scientific -> Value # toEncoding :: Scientific -> Encoding # toJSONList :: [Scientific] -> Value # toEncodingList :: [Scientific] -> Encoding # omitField :: Scientific -> Bool #

Encoding

Decoding

Decoding multiple documents

More control over decoding

Types

Instances

Instances

Instances

Instances

Instances

Constructors and accessors

With helpers (since 0.8.23)

Parsing

Classes

Instances

Instances

Custom encoding

Deprecated