-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Support for parsing and rendering YAML documents.
--
-- Provides support for parsing and emitting Yaml documents.
--
-- This package includes the full libyaml C library version 0.1.2 by
-- Kirill Simonov (<a>http://pyyaml.org/wiki/LibYAML</a>) in the package
-- so you don't need to worry about any non-Haskell dependencies.
--
-- The package is broken down into two modules. <a>Data.Yaml</a> provides
-- a high-level interface based around the JSON datatypes provided by the
-- <tt>aeson</tt> package. <a>Text.Libyaml</a> provides a lower-level,
-- streaming interface. For most users, <a>Data.Yaml</a> is recommended.
@package yaml
@version 0.8.5.2
-- | Low-level, streaming YAML interface. For a higher-level interface, see
-- <a>Data.Yaml</a>.
module Text.Libyaml
data Event
EventStreamStart :: Event
EventStreamEnd :: Event
EventDocumentStart :: Event
EventDocumentEnd :: Event
EventAlias :: !AnchorName -> Event
EventScalar :: !ByteString -> !Tag -> !Style -> !Anchor -> Event
EventSequenceStart :: !Anchor -> Event
EventSequenceEnd :: Event
EventMappingStart :: !Anchor -> Event
EventMappingEnd :: Event
data Style
Any :: Style
Plain :: Style
SingleQuoted :: Style
DoubleQuoted :: Style
Literal :: Style
Folded :: Style
PlainNoTag :: Style
data Tag
StrTag :: Tag
FloatTag :: Tag
NullTag :: Tag
BoolTag :: Tag
SetTag :: Tag
IntTag :: Tag
SeqTag :: Tag
MapTag :: Tag
UriTag :: String -> Tag
NoTag :: Tag
type AnchorName = String
type Anchor = Maybe AnchorName
encode :: MonadResource m => Consumer Event m ByteString
decode :: MonadResource m => ByteString -> Producer m Event
encodeFile :: MonadResource m => FilePath -> Consumer Event m ()
decodeFile :: MonadResource m => FilePath -> Producer m Event
data YamlException
YamlException :: String -> YamlException
-- | problem, context, index, position line, position column
YamlParseException :: String -> String -> YamlMark -> YamlException
yamlProblem :: YamlException -> String
yamlContext :: YamlException -> String
yamlProblemMark :: YamlException -> YamlMark
-- | The pointer position
data YamlMark
YamlMark :: Int -> Int -> Int -> YamlMark
yamlIndex :: YamlMark -> Int
yamlLine :: YamlMark -> Int
yamlColumn :: YamlMark -> Int
instance Typeable Style
instance Typeable Tag
instance Typeable ToEventRawException
instance Typeable YamlException
instance Show Style
instance Read Style
instance Eq Style
instance Enum Style
instance Bounded Style
instance Ord Style
instance Data Style
instance Show Tag
instance Eq Tag
instance Read Tag
instance Data Tag
instance Show Event
instance Eq Event
instance Enum EventType
instance Show EventType
instance Show ToEventRawException
instance Show YamlMark
instance Show YamlException
instance Exception YamlException
instance Exception ToEventRawException
-- | Provides a high-level interface for processing YAML files.
--
-- This module reuses most of the infrastructure from the <tt>aeson</tt>
-- 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 <a>Text.Libyaml</a> module instead.
--
-- For documentation on the <tt>aeson</tt> types, functions, classes, and
-- operators, please see the <tt>Data.Aeson</tt> module of the
-- <tt>aeson</tt> package.
module Data.Yaml
-- | A JSON value represented as a Haskell value.
data Value :: *
Object :: !Object -> Value
Array :: !Array -> Value
String :: !Text -> Value
Number :: !Number -> Value
Bool :: !Bool -> Value
Null :: Value
-- | A continuation-based parser type.
data Parser a :: * -> *
-- | A JSON "object" (key/value map).
type Object = HashMap Text Value
-- | A JSON "array" (sequence).
type Array = Vector Value
data ParseException
NonScalarKey :: ParseException
UnknownAlias :: AnchorName -> ParseException
_anchorName :: ParseException -> AnchorName
UnexpectedEvent :: Maybe Event -> Maybe Event -> ParseException
_received :: ParseException -> Maybe Event
_expected :: ParseException -> Maybe Event
InvalidYaml :: (Maybe YamlException) -> ParseException
AesonException :: String -> ParseException
OtherParseException :: SomeException -> ParseException
data YamlException
YamlException :: String -> YamlException
-- | problem, context, index, position line, position column
YamlParseException :: String -> String -> YamlMark -> YamlException
yamlProblem :: YamlException -> String
yamlContext :: YamlException -> String
yamlProblemMark :: YamlException -> YamlMark
-- | The pointer position
data YamlMark
YamlMark :: Int -> Int -> Int -> YamlMark
yamlIndex :: YamlMark -> Int
yamlLine :: YamlMark -> Int
yamlColumn :: YamlMark -> Int
-- | Create a <a>Value</a> from a list of name/value <a>Pair</a>s. If
-- duplicate keys arise, earlier keys and their associated values win.
object :: [Pair] -> Value
array :: [Value] -> Value
-- | Construct a <a>Pair</a> from a key and a value.
(.=) :: ToJSON a => Text -> a -> Pair
-- | Retrieve the value associated with the given key of an <a>Object</a>.
-- The result is <tt>empty</tt> if the key is not present or the value
-- cannot be converted to the desired type.
--
-- This accessor is appropriate if the key and value <i>must</i> be
-- present in an object for it to be valid. If the key and value are
-- optional, use '(.:?)' instead.
(.:) :: FromJSON a => Object -> Text -> Parser a
-- | Retrieve the value associated with the given key of an <a>Object</a>.
-- The result is <a>Nothing</a> if the key is not present, or
-- <tt>empty</tt> if the value cannot be converted to the desired type.
--
-- This accessor is most useful if the key and value can be absent from
-- an object without affecting its validity. If the key and value are
-- mandatory, use '(.:)' instead.
(.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a)
-- | Helper for use in combination with <a>.:?</a> to provide default
-- values for optional JSON object fields.
--
-- This combinator is most useful if the key and value can be absent from
-- an object without affecting its validity and we know a default value
-- to assign in that case. If the key and value are mandatory, use '(.:)'
-- instead.
--
-- Example usage:
--
-- <pre>
-- v1 <- o <a>.:?</a> "opt_field_with_dfl" .!= "default_val"
-- v2 <- o <a>.:</a> "mandatory_field"
-- v3 <- o <a>.:?</a> "opt_field2"
-- </pre>
(.!=) :: Parser (Maybe a) -> a -> Parser a
parseMonad :: Monad m => (a -> Parser b) -> a -> m b
-- | Run a <a>Parser</a> with an <a>Either</a> result type.
parseEither :: (a -> Parser b) -> a -> Either String b
-- | Run a <a>Parser</a> with a <a>Maybe</a> result type.
parseMaybe :: (a -> Parser b) -> a -> Maybe b
-- | A type that can be converted to JSON.
--
-- An example type and instance:
--
-- <pre>
-- {-# LANGUAGE OverloadedStrings #-}
--
-- data Coord { x :: Double, y :: Double }
--
-- instance ToJSON Coord where
-- toJSON (Coord x y) = <a>object</a> ["x" <a>.=</a> x, "y" <a>.=</a> y]
-- </pre>
--
-- Note the use of the <tt>OverloadedStrings</tt> language extension
-- which enables <a>Text</a> values to be written as string literals.
--
-- Instead of manually writing your <a>ToJSON</a> instance, there are
-- three options to do it automatically:
--
-- <ul>
-- <li><a>Data.Aeson.TH</a> provides template-haskell functions which
-- will derive an instance at compile-time. The generated instance is
-- optimized for your type so will probably be more efficient than the
-- following two options:</li>
-- <li><a>Data.Aeson.Generic</a> provides a generic <tt>toJSON</tt>
-- function that accepts any type which is an instance of
-- <tt>Data</tt>.</li>
-- <li>If your compiler has support for the <tt>DeriveGeneric</tt> and
-- <tt>DefaultSignatures</tt> language extensions, <tt>toJSON</tt> will
-- have a default generic implementation.</li>
-- </ul>
--
-- To use the latter option, simply add a <tt>deriving
-- <a>Generic</a></tt> clause to your datatype and declare a
-- <tt>ToJSON</tt> instance for your datatype without giving a definition
-- for <tt>toJSON</tt>.
--
-- For example the previous example can be simplified to just:
--
-- <pre>
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics
--
-- data Coord { x :: Double, y :: Double } deriving Generic
--
-- instance ToJSON Coord
-- </pre>
class ToJSON a
toJSON :: ToJSON a => a -> Value
-- | A type that can be converted from JSON, with the possibility of
-- failure.
--
-- When writing an instance, use <tt>empty</tt>, <tt>mzero</tt>, or
-- <a>fail</a> to make a conversion fail, e.g. if an <a>Object</a> is
-- missing a required key, or the value is of the wrong type.
--
-- An example type and instance:
--
-- <pre>
-- {-# LANGUAGE OverloadedStrings #-}
--
-- data Coord { x :: Double, y :: Double }
--
-- instance FromJSON Coord where
-- parseJSON (<a>Object</a> v) = Coord <a><$></a>
-- v <a>.:</a> "x" <a><*></a>
-- v <a>.:</a> "y"
--
-- -- A non-<a>Object</a> value is of the wrong type, so use <tt>mzero</tt> to fail.
-- parseJSON _ = <tt>mzero</tt>
-- </pre>
--
-- Note the use of the <tt>OverloadedStrings</tt> language extension
-- which enables <a>Text</a> values to be written as string literals.
--
-- Instead of manually writing your <a>FromJSON</a> instance, there are
-- three options to do it automatically:
--
-- <ul>
-- <li><a>Data.Aeson.TH</a> provides template-haskell functions which
-- will derive an instance at compile-time. The generated instance is
-- optimized for your type so will probably be more efficient than the
-- following two options:</li>
-- <li><a>Data.Aeson.Generic</a> provides a generic <tt>fromJSON</tt>
-- function that parses to any type which is an instance of
-- <tt>Data</tt>.</li>
-- <li>If your compiler has support for the <tt>DeriveGeneric</tt> and
-- <tt>DefaultSignatures</tt> language extensions, <tt>parseJSON</tt>
-- will have a default generic implementation.</li>
-- </ul>
--
-- To use this, simply add a <tt>deriving <a>Generic</a></tt> clause to
-- your datatype and declare a <tt>FromJSON</tt> instance for your
-- datatype without giving a definition for <tt>parseJSON</tt>.
--
-- For example the previous example can be simplified to just:
--
-- <pre>
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics
--
-- data Coord { x :: Double, y :: Double } deriving Generic
--
-- instance FromJSON Coord
-- </pre>
class FromJSON a
parseJSON :: FromJSON a => Value -> Parser a
encode :: ToJSON a => a -> ByteString
encodeFile :: ToJSON a => FilePath -> a -> IO ()
decode :: FromJSON a => ByteString -> Maybe a
decodeFile :: FromJSON a => FilePath -> IO (Maybe a)
decodeEither :: FromJSON a => ByteString -> Either String a
-- | More helpful version of <a>decodeEither</a> which returns the
-- <a>YamlException</a>.
--
-- Since 0.8.3
decodeEither' :: FromJSON a => ByteString -> Either ParseException a
-- | A version of <a>decodeFile</a> which should not throw runtime
-- exceptions.
--
-- Since 0.8.4
decodeFileEither :: FromJSON a => FilePath -> IO (Either ParseException a)
decodeHelper :: FromJSON a => Source Parse Event -> IO (Either ParseException (Either String a))
instance Typeable ParseException
instance Show ParseException
instance MonadIO m => MonadIO (PErrorT m)
instance MonadTrans PErrorT
instance Monad m => Monad (PErrorT m)
instance Exception ParseException
