data-object-yaml 0.3.3.3 → 0.3.3.4

raw patch · 2 files changed

+100/−1 lines, 2 files

Files

• Data/Object/Yaml.hs +99/−0
• data-object-yaml.cabal +1/−1

@@ -4,6 +4,105 @@ {-# LANGUAGE DeriveDataTypeable #-} {-# LANGUAGE MultiParamTypeClasses #-} {-# LANGUAGE PackageImports #-}+{-|+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:++@+    data Object k v = Scalar v+                    | Sequence [Object k v]+                    | Mapping [(k, Object k v)]+@++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 -> String) and ones which may fail (String -> Int),+and also supports various textual datatypes (String, lazy\/strict ByteString,+lazy\/string Text).++/YamlScalar and YamlObject/++We have a @type YamlObject = Object YamlScalar YamlScalar@, 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.++/Encoding and decoding/++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:++@+    encodeFile "myfile.yaml" $ Mapping+        [ ("Michael", Mapping+            [ ("age", Scalar "26")+            , ("color", Scalar "blue")+            ])+        , ("Eliezer", Mapping+            [ ("age", Scalar "2")+            , ("color", Scalar "green")+            ])+        ]+@++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:++@+    maybeObject <- decodeFile "myfile.yaml"+    case maybeObject of+        Nothing -> putStrLn "Error parsing YAML file."+        Just object -> putStrLn "Successfully parsed."+@++If you just want to throw any parse errors as IO exception, you can use join:++@+    import Control.Monad (join)+    object <- join $ decodeFile "myfile.yaml"+@++This takes advantage of the IO instance of Failure.++/Parsing an Object/++In order to pull the data out of an Object, you can use the helper functions+from Data.Object. For example:++@+    import Data.Object+    import Data.Object.Yaml+    import Control.Monad++    main = do+        object <- join $ decodeFile "myfile.yaml"+        people <- fromMapping object+        michael <- lookupMapping "Michael" people+        age <- lookupScalar "age" michael+        putStrLn $ "Michael is " ++ age ++ " years old."+@++/And that's it/++There's really not more to know about this library. Enjoy!+-} module Data.Object.Yaml     ( -- * Definition of 'YamlObject'       YamlScalar (..)

@@ -1,5 +1,5 @@ name:            data-object-yaml-version:         0.3.3.3+version:         0.3.3.4 license:         BSD3 license-file:    LICENSE author:          Michael Snoyman <michael@snoyman.com>, Anton Ageev <antage@gmail.com>