-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Serialize data to and from Yaml files (deprecated)
--   
--   Future development will focus on the Data.Yaml module of the yaml
--   package, which leverages aeson's existing Value type. This package is
--   officially deprecated. Provides high level conversions based on the
--   data-object package. Parsing and emitting is handled by the yaml
--   package, which in turn uses the libyaml C library.
@package data-object-yaml
@version 0.3.4


-- | As a bit of background, this package is built on a few other packages
--   I wrote. yaml is a low-level wrapper around the C libyaml library,
--   with an enumerator interface. data-object is a package defining a data
--   type:
--   
--   <pre>
--   data Object k v = Scalar v
--                   | Sequence [Object k v]
--                   | Mapping [(k, Object k v)]
--   </pre>
--   
--   In other words, it can represent JSON data fully, and YAML data almost
--   fully. In particular, it doesn't handle cyclical aliases, which I hope
--   doesn't really occur too much in real life.
--   
--   Another package to deal with is failure: it basically replaces using
--   an Either for error-handling into a typeclass. It has instances for
--   Maybe, IO and lists by default.
--   
--   The last package is convertible-text, which is a fork of John
--   Goerzen's convertible package. The difference is it supports both
--   conversions that are guaranteed to succeed (Int -&gt; String) and ones
--   which may fail (String -&gt; Int), and also supports various textual
--   datatypes (String, lazy/strict ByteString, lazy/string Text).
--   
--   <i>YamlScalar and YamlObject</i>
--   
--   We have a <tt>type YamlObject = Object YamlScalar YamlScalar</tt>,
--   where a YamlScalar is just a ByteString value with a tag and a style.
--   A "style" is how the data was represented in the underlying YAML file:
--   single quoted, double quoted, etc.
--   
--   Then there is an IsYamlScalar typeclass, which provides fromYamlScalar
--   and toYamlScalar conversion functions. There are instances for all the
--   "text-like" datatypes: String, ByteString and Text. The built-in
--   instances all assume a UTF-8 data encoding. And around this we have
--   toYamlObject and fromYamlObject functions, which do exactly what they
--   sound like.
--   
--   <i>Encoding and decoding</i>
--   
--   There are two encoding files: encode and encodeFile. You can guess the
--   different: the former produces a ByteString (strict) and the latter
--   writes to a file. They both take an Object, whose keys and values must
--   be an instance of IsYamlScalar. So, for example:
--   
--   <pre>
--   encodeFile <a>myfile.yaml</a> $ Mapping
--       [ (<a>Michael</a>, Mapping
--           [ (<a>age</a>, Scalar <a>26</a>)
--           , (<a>color</a>, Scalar <a>blue</a>)
--           ])
--       , (<a>Eliezer</a>, Mapping
--           [ (<a>age</a>, Scalar <a>2</a>)
--           , (<a>color</a>, Scalar <a>green</a>)
--           ])
--       ]
--   </pre>
--   
--   decoding is only slightly more complicated, since the decoding can
--   fail. In particular, the return type is an IO wrapped around a
--   Failure. For example, you could use:
--   
--   <pre>
--   maybeObject &lt;- decodeFile <a>myfile.yaml</a>
--   case maybeObject of
--       Nothing -&gt; putStrLn <a>Error parsing YAML file.</a>
--       Just object -&gt; putStrLn <a>Successfully parsed.</a>
--   </pre>
--   
--   If you just want to throw any parse errors as IO exception, you can
--   use join:
--   
--   <pre>
--   import Control.Monad (join)
--   object &lt;- join $ decodeFile <a>myfile.yaml</a>
--   </pre>
--   
--   This takes advantage of the IO instance of Failure.
--   
--   <i>Parsing an Object</i>
--   
--   In order to pull the data out of an Object, you can use the helper
--   functions from Data.Object. For example:
--   
--   <pre>
--       import Data.Object
--       import Data.Object.Yaml
--       import Control.Monad
--   
--   main = do
--           object &lt;- join $ decodeFile <a>myfile.yaml</a>
--           people &lt;- fromMapping object
--           michael &lt;- lookupMapping <a>Michael</a> people
--           age &lt;- lookupScalar <a>age</a> michael
--           putStrLn $ <a>Michael is </a> ++ age ++ <a> years old.</a>
--   </pre>
--   
--   lookupScalar and friends implement Maybe, so you can test for optional
--   attributes by switching on Nothing/Just a:
--   
--   <pre>
--   name &lt;- lookupScalar <a>middleName</a> michael :: Maybe String
--   </pre>
--   
--   <i>And that's it</i>
--   
--   There's really not more to know about this library. Enjoy!
module Data.Object.Yaml

-- | Equality depends on <a>value</a> and <a>tag</a>, not <a>style</a>.
data YamlScalar
YamlScalar :: ByteString -> Tag -> Style -> YamlScalar
value :: YamlScalar -> ByteString
tag :: YamlScalar -> Tag
style :: YamlScalar -> Style
type YamlObject = Object YamlScalar YamlScalar
class Eq a => IsYamlScalar a
fromYamlScalar :: IsYamlScalar a => YamlScalar -> a
toYamlScalar :: IsYamlScalar a => a -> YamlScalar
toYamlObject :: IsYamlScalar k => IsYamlScalar v => Object k v -> YamlObject
fromYamlObject :: IsYamlScalar k => IsYamlScalar v => YamlObject -> Object k v
encode :: (IsYamlScalar k, IsYamlScalar v) => Object k v -> ByteString
encodeFile :: (IsYamlScalar k, IsYamlScalar v) => FilePath -> Object k v -> IO ()
decode :: (Failure ParseException m, IsYamlScalar k, IsYamlScalar v) => ByteString -> m (Object k v)
decodeFile :: (Failure ParseException m, IsYamlScalar k, IsYamlScalar v) => FilePath -> IO (m (Object k v))
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 String) -> ParseException
instance Typeable YamlScalar
instance Typeable ParseException
instance Show YamlScalar
instance Read YamlScalar
instance Data YamlScalar
instance Show ParseException
instance MonadIO m => MonadIO (PErrorT m)
instance MonadTrans PErrorT
instance Monad m => Monad (PErrorT m)
instance Exception ParseException
instance IsYamlScalar ByteString
instance IsYamlScalar ByteString
instance IsYamlScalar [Char]
instance IsYamlScalar Text
instance IsYamlScalar Text
instance IsYamlScalar YamlScalar
instance IsString YamlScalar
instance Eq YamlScalar