-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Declaritive configuration parsing with free docs -- -- See https://github.com/NorfairKing/yamlparse-applicative @package yamlparse-applicative @version 0.2.0.0 module YamlParse.Applicative.Parser -- | A parser that takes values of type i as input and parses them -- into values of type o -- -- Note that there is no Monad instance. data Parser i o -- | Return the input [ParseAny] :: Parser i i -- | Parse via an extra parsing function [ParseExtra] :: (o -> Parser u) -> Parser i o -> Parser i u -- | Match an exact value [ParseEq] :: (Show o, Eq o) => o -> Text -> Parser i o -> Parser i o -- | Parse null only. [ParseNull] :: Parser Value () -- | Parse null as Nothing and the rest as Just. [ParseMaybe] :: Parser Value o -> Parser Value (Maybe o) -- | Parse a boolean value [ParseBool] :: Maybe Text -> Parser Bool o -> Parser Value o -- | Parse a String value [ParseString] :: Maybe Text -> Parser Text o -> Parser Value o -- | Parse a numeric value [ParseNumber] :: Maybe Text -> Parser Scientific o -> Parser Value o -- | Parse an array [ParseArray] :: Maybe Text -> Parser Array o -> Parser Value o -- | Parse an object [ParseObject] :: Maybe Text -> Parser Object a -> Parser Value a -- | Parse a list of elements all in the same way [ParseList] :: Parser Value o -> Parser Array (Vector o) -- | Parse a map where the keys are the yaml keys [ParseMap] :: Parser Value v -> Parser Object (HashMap Text v) -- | Parse a map's keys via a given parser [ParseMapKeys] :: Ord k => Parser Text k -> Parser Object (HashMap Text v) -> Parser Object (Map k v) -- | Parse a field of an object [ParseField] :: Text -> FieldParser o -> Parser Object o -- | A pure value [ParsePure] :: a -> Parser i a -- | To implement Functor [ParseFmap] :: (a -> b) -> Parser i a -> Parser i b -- | To implement Applicative [ParseAp] :: Parser i (a -> b) -> Parser i a -> Parser i b -- | To implement Alternative [ParseAlt] :: [Parser i o] -> Parser i o -- | Add comments to the parser. This info will be used in the schema for -- documentation. [ParseComment] :: Text -> Parser i o -> Parser i o data FieldParser o [FieldParserFmap] :: (a -> b) -> FieldParser a -> FieldParser b [FieldParserRequired] :: YamlParser o -> FieldParser o [FieldParserOptional] :: YamlParser o -> FieldParser (Maybe o) [FieldParserOptionalWithDefault] :: Show o => YamlParser o -> o -> FieldParser o type YamlParser a = Parser Value a type ObjectParser a = Parser Object a type KeyParser a = Parser Text a -- | Declare a parser of a named object objectParser :: Text -> ObjectParser o -> YamlParser o -- | Declare a parser of an unnamed object -- -- Prefer objectParser if you can. unnamedObjectParser :: ObjectParser o -> YamlParser o -- | Parse a string-like thing by Read-ing it -- -- You probably don't want to use Read. viaRead :: Read a => YamlParser a -- | Declare a parser for an exact string. -- -- You can use this to parse a constructor in an enum for example: -- -- 
--   data Fruit = Apple | Banana
--   
--   instance YamlSchema Fruit where
--     yamlSchema = Apple <$ literalString "Apple" <|> Banana <$ literalString "Banana"
--
literalString :: Text -> YamlParser Text -- | Declare a parser for a value using its show instance -- -- Note that no value is read. The parsed string is just compared to the -- shown given value. -- -- You can use this to parse a constructor in an enum when it has a -- Show instance. -- -- For example: -- -- 
--   data Fruit = Apple | Banana | Melon
--     deriving (Show, Eq)
--   
--   instance YamlSchema Fruit where
--     yamlSchema = alternatives
--        [ literalShowString Apple
--        , literalShowString Banana
--        , literalShowString Melon
--        ]
--
literalShowValue :: Show a => a -> YamlParser a -- | Declare a parser for a value using its show instance -- -- Note that no value is read. The parsed string is just compared to the -- shown given value. -- -- You can use this to parse a constructor in an enum when it has a -- ToJSON instance. -- -- For example -- -- 
--   data Fruit = Apple | Banana | Melon
--     deriving (Eq, Generic)
--   
--   instance ToJSON Fruit
--   
--   instance YamlSchema Fruit where
--     yamlSchema = alternatives
--        [ literalValue Apple
--        , literalValue Banana
--        , literalValue Melon
--        ]
--
literalValue :: ToJSON a => a -> YamlParser a -- | Use the first parser of the given list that succeeds -- -- You can use this to parse a constructor in an enum. -- -- For example: -- -- 
--   data Fruit = Apple | Banana | Melon
--   
--   instance YamlSchema Fruit where
--     yamlSchema = alternatives
--        [ Apple <$ literalString "Apple"
--        , Banana <$ literalString "Banana"
--        , Melon <$ literalString "Melon"
--        ]
--
alternatives :: [Parser i o] -> Parser i o -- | Add a comment to a parser -- -- This info will be used in the schema for documentation. -- -- For example: -- -- 
--   data Result = Error | Ok
--   instance YamlSchema Result where
--     yamlSchema = alternatives
--       [ Error <$ literalString "Error" <?> "An error"
--       , Ok <$ literalString "Ok" <?> "Oll Klear"
--       ]
--
() :: Parser i a -> Text -> Parser i a -- | Add a list of lines of comments to a parser -- -- This info will be used in the schema for documentation. -- -- For example: -- -- 
--   data Result = Error | Ok
--   instance YamlSchema Result where
--     yamlSchema = alternatives
--       [ Error <$ literalString "Error" <??> ["Just an error", "but I've got a lot to say about this"]
--       , Ok <$ literalString "Ok" <??> ["Oll Klear", "I really don't know where 'OK' comes from?!"]
--       ]
--
() :: Parser i a -> [Text] -> Parser i a -- | A parser for a required field at a given key with a parser for what is -- found at that key requiredFieldWith :: Text -> Text -> YamlParser a -> ObjectParser a -- | A parser for a required field at a given key with a parser for what is -- found at that key without a help text requiredFieldWith' :: Text -> YamlParser a -> ObjectParser a -- | A parser for an optional field at a given key with a parser for what -- is found at that key optionalFieldWith :: Text -> Text -> YamlParser a -> ObjectParser (Maybe a) -- | A parser for an optional field at a given key with a parser for what -- is found at that key without a help text optionalFieldWith' :: Text -> YamlParser a -> ObjectParser (Maybe a) -- | A parser for an optional field at a given key with a default value and -- a parser for what is found at that key -- -- For the sake of documentation, the default value needs to be showable. optionalFieldWithDefaultWith :: Show a => Text -> a -> Text -> YamlParser a -> ObjectParser a -- | A parser for an optional field at a given key with a default value and -- a parser for what is found at that key without a help text -- -- For the sake of documentation, the default value needs to be showable. optionalFieldWithDefaultWith' :: Show a => Text -> a -> YamlParser a -> ObjectParser a -- | Make a parser that parses a value using the given extra parsing -- function -- -- You can use this to make a parser for a type with a smart constructor. -- Prefer eitherParser if you can so you get better error -- messages. -- -- Example: -- -- 
--   parseUsername :: Text -> Maybe Username
--   
--   instance YamlSchema Username where
--     yamlSchema = maybeParser parseUsername yamlSchema
--
maybeParser :: Show o => (o -> Maybe u) -> Parser i o -> Parser i u -- | Make a parser that parses a value using the given extra parsing -- function -- -- You can use this to make a parser for a type with a smart constructor. -- If you don't have a Show instance for your o, then you -- can use extraParser instead. -- -- Example: -- -- 
--   parseUsername :: Text -> Either String Username
--   
--   instance YamlSchema Username where
--     yamlSchema = eitherParser parseUsername yamlSchema
--
eitherParser :: Show o => (o -> Either String u) -> Parser i o -> Parser i u -- | Make a parser that parses a value using the given extra parsing -- function -- -- You can use this to make a parser for a type with a smart constructor. -- Prefer eitherParser if you can, use this if you don't have a -- Show instance for your o. extraParser :: (o -> Parser u) -> Parser i o -> Parser i u instance GHC.Base.Functor (YamlParse.Applicative.Parser.Parser i) instance GHC.Base.Applicative (YamlParse.Applicative.Parser.Parser i) instance GHC.Base.Alternative (YamlParse.Applicative.Parser.Parser i) instance GHC.Base.Functor YamlParse.Applicative.Parser.FieldParser module YamlParse.Applicative.Implement -- | Use a Parser to parse a value from Yaml. -- -- A 'Parser i o' corresponds exactly to a 'i -> Yaml.Parser o' and -- this function servers as evidence for that. implementParser :: Parser i o -> i -> Parser o module YamlParse.Applicative.Explain data Schema EmptySchema :: Schema AnySchema :: Schema ExactSchema :: Text -> Schema NullSchema :: Schema MaybeSchema :: Schema -> Schema BoolSchema :: Maybe Text -> Schema NumberSchema :: Maybe Text -> Schema StringSchema :: Maybe Text -> Schema ArraySchema :: Maybe Text -> Schema -> Schema ObjectSchema :: Maybe Text -> Schema -> Schema FieldSchema :: Text -> Bool -> Maybe Text -> Schema -> Schema ListSchema :: Schema -> Schema MapSchema :: Schema -> Schema MapKeysSchema :: Schema -> Schema ApSchema :: Schema -> Schema -> Schema AltSchema :: [Schema] -> Schema CommentSchema :: Text -> Schema -> Schema -- | Use a parser to produce a schema that describes it for documentation. -- -- Nothing means that nothing even needs to be parsed, you just get the -- a without parsing anything. This is for the pure case. explainParser :: Parser i o -> Schema instance GHC.Generics.Generic YamlParse.Applicative.Explain.Schema instance GHC.Classes.Eq YamlParse.Applicative.Explain.Schema instance GHC.Show.Show YamlParse.Applicative.Explain.Schema instance Data.Validity.Validity YamlParse.Applicative.Explain.Schema module YamlParse.Applicative.Class -- | A class of types for which a schema is defined. -- -- Note that you do not have to use this class and can just use your own -- parser values. Note also that the parsing of a type of this class -- should correspond to the parsing of the type in the FromJSON class. class YamlSchema a -- | A yamlschema for one value -- -- See the sections on helper functions for implementing this for plenty -- of examples. yamlSchema :: YamlSchema a => YamlParser a -- | A yamlschema for a list of values -- -- This is really only useful for cases like Char and -- String yamlSchemaList :: YamlSchema a => YamlParser [a] -- | A class of types for which a schema for keys is defined. class YamlKeySchema a yamlKeySchema :: YamlKeySchema a => KeyParser a boundedIntegerSchema :: (Integral i, Bounded i) => YamlParser i -- | A parser for a required field in an object at a given key requiredField :: YamlSchema a => Text -> Text -> ObjectParser a -- | A parser for a required field in an object at a given key without a -- help text requiredField' :: YamlSchema a => Text -> ObjectParser a -- | A parser for an optional field in an object at a given key optionalField :: YamlSchema a => Text -> Text -> ObjectParser (Maybe a) -- | A parser for an optional field in an object at a given key without a -- help text optionalField' :: YamlSchema a => Text -> ObjectParser (Maybe a) -- | A parser for an optional field in an object at a given key with a -- default value optionalFieldWithDefault :: (Show a, YamlSchema a) => Text -> a -> Text -> ObjectParser a -- | A parser for an optional field in an object at a given key with a -- default value without a help text optionalFieldWithDefault' :: (Show a, YamlSchema a) => Text -> a -> ObjectParser a -- | Helper function to implement FromJSON via YamlSchema -- -- Example: -- -- 
--   instance FromJSON Config where
--     parseJSON = viaYamlSchema
--
viaYamlSchema :: YamlSchema a => Value -> Parser a -- | A helper newtype to parse a yaml value using the YamlSchema parser. -- -- Example: -- -- 
--   case Data.Yaml.decodeEither' contents of
--     Left e -> die $ show e
--     Right (ViaYamlSchema res) -> print res
--
-- -- This only helps you when you really don't want to implement a -- FromJSON instance. See viaYamlSchema if you do. newtype ViaYamlSchema a ViaYamlSchema :: a -> ViaYamlSchema a instance GHC.Generics.Generic (YamlParse.Applicative.Class.ViaYamlSchema a) instance GHC.Classes.Eq a => GHC.Classes.Eq (YamlParse.Applicative.Class.ViaYamlSchema a) instance GHC.Show.Show a => GHC.Show.Show (YamlParse.Applicative.Class.ViaYamlSchema a) instance YamlParse.Applicative.Class.YamlSchema a => Data.Aeson.Types.FromJSON.FromJSON (YamlParse.Applicative.Class.ViaYamlSchema a) instance YamlParse.Applicative.Class.YamlKeySchema Data.Text.Internal.Text instance YamlParse.Applicative.Class.YamlKeySchema GHC.Base.String instance (GHC.Classes.Ord k, YamlParse.Applicative.Class.YamlKeySchema k, YamlParse.Applicative.Class.YamlSchema v) => YamlParse.Applicative.Class.YamlSchema (Data.Map.Internal.Map k v) instance YamlParse.Applicative.Class.YamlSchema () instance YamlParse.Applicative.Class.YamlSchema GHC.Types.Bool instance YamlParse.Applicative.Class.YamlSchema GHC.Types.Char instance YamlParse.Applicative.Class.YamlSchema Data.Text.Internal.Text instance YamlParse.Applicative.Class.YamlSchema Data.Scientific.Scientific instance YamlParse.Applicative.Class.YamlSchema GHC.Types.Int instance YamlParse.Applicative.Class.YamlSchema GHC.Int.Int8 instance YamlParse.Applicative.Class.YamlSchema GHC.Int.Int16 instance YamlParse.Applicative.Class.YamlSchema GHC.Int.Int32 instance YamlParse.Applicative.Class.YamlSchema GHC.Int.Int64 instance YamlParse.Applicative.Class.YamlSchema GHC.Types.Word instance YamlParse.Applicative.Class.YamlSchema GHC.Word.Word8 instance YamlParse.Applicative.Class.YamlSchema GHC.Word.Word16 instance YamlParse.Applicative.Class.YamlSchema GHC.Word.Word32 instance YamlParse.Applicative.Class.YamlSchema GHC.Word.Word64 instance YamlParse.Applicative.Class.YamlSchema (Path.Internal.Path Path.Posix.Rel Path.Posix.File) instance YamlParse.Applicative.Class.YamlSchema (Path.Internal.Path Path.Posix.Rel Path.Posix.Dir) instance YamlParse.Applicative.Class.YamlSchema (Path.Internal.Path Path.Posix.Abs Path.Posix.File) instance YamlParse.Applicative.Class.YamlSchema (Path.Internal.Path Path.Posix.Abs Path.Posix.Dir) instance YamlParse.Applicative.Class.YamlSchema Data.Aeson.Types.Internal.Value instance YamlParse.Applicative.Class.YamlSchema a => YamlParse.Applicative.Class.YamlSchema (GHC.Maybe.Maybe a) instance YamlParse.Applicative.Class.YamlSchema a => YamlParse.Applicative.Class.YamlSchema (Data.Vector.Vector a) instance YamlParse.Applicative.Class.YamlSchema a => YamlParse.Applicative.Class.YamlSchema [a] instance YamlParse.Applicative.Class.YamlSchema a => YamlParse.Applicative.Class.YamlSchema (GHC.Base.NonEmpty a) instance (GHC.Classes.Ord a, YamlParse.Applicative.Class.YamlSchema a) => YamlParse.Applicative.Class.YamlSchema (Data.Set.Internal.Set a) instance YamlParse.Applicative.Class.YamlSchema v => YamlParse.Applicative.Class.YamlSchema (Data.HashMap.Internal.HashMap Data.Text.Internal.Text v) module YamlParse.Applicative.Pretty data Colour Yellow :: Colour Gray :: Colour Red :: Colour Blue :: Colour White :: Colour -- | Render pretty documentation about the yamlSchema of a type -- -- This is meant for humans. The output may look like YAML but it is not. prettySchemaDoc :: forall a. YamlSchema a => Text -- | Render pretty documentation about a parser -- -- This is meant for humans. The output may look like YAML but it is not. prettyParserDoc :: Parser i o -> Text -- | Render pretty colourised documentation about the yamlSchema of -- a type -- -- This is meant for humans. The output may look like YAML but it is not. prettyColourisedSchemaDoc :: forall a. YamlSchema a => Text -- | Render pretty colourised documentation about a parser -- -- This is meant for humans. The output may look like YAML but it is not. prettyColourisedParserDoc :: Parser i o -> Text -- | Render a schema as pretty text. -- -- This is meant for humans. The output may look like YAML but it is not. prettySchema :: Schema -> Text -- | Render a schema as pretty and colourised text. -- -- This is meant for humans. The output may look like YAML but it is not. prettyColourisedSchema :: Schema -> Text -- | A list of comments newtype Comments Comments :: [Doc Colour] -> Comments [commentsList] :: Comments -> [Doc Colour] -- | No comments emptyComments :: Comments -- | A raw text as comments comment :: Text -> Comments -- | Prettyprint a Schema schemaDoc :: Schema -> Doc Colour instance GHC.Show.Show YamlParse.Applicative.Pretty.Comments instance GHC.Base.Semigroup YamlParse.Applicative.Pretty.Comments instance GHC.Base.Monoid YamlParse.Applicative.Pretty.Comments module YamlParse.Applicative.OptParse -- | Helper function to add the schema documentation for a -- YamlSchema parser to the optparse applicative help output confDesc :: forall o a. YamlSchema o => InfoMod a -- | Helper function to add the schema documentation for a given parser to -- the optparse applicative help output confDescWith :: Parser i o -> InfoMod a module YamlParse.Applicative.IO -- | Helper function to read a config file for a type in YamlSchema readConfigFile :: (YamlSchema a, FromJSON a) => Path r File -> IO (Maybe a) -- | Helper function to read the first in a list of config files readFirstConfigFile :: forall a r. (FromJSON a, YamlSchema a) => [Path r File] -> IO (Maybe a) -- | Yamlparse applicative -- -- Implement Yaml parsing and get documentation for it for free. -- --

Usage example

-- -- For more examples, see the `yamlparse-applicative-demo` examples in -- the github repository -- -- Suppose you have some tool and you want to have it read its -- configuration from a file. You make a type for the configuration: -- -- 
--   data Configuration
--     = Configuration
--     { confUrl :: Maybe Text
--     , confPort :: Int
--     , confToken :: Text
--     } deriving (Show, Eq)
--
-- -- Instead of implementing a FromJSON instance, you now implement -- a YamlSchema instance like so: -- -- 
--   instance YamlSchema Configuration where
--     yamlSchema =
--       objectParser $ -- Declare that it is a Yaml object
--         Configuration
--           <$> optionalField -- An optional key may be in the file
--               "url"
--               "The url to host the server at. It will be hosted on 'localhost' by default."
--           <*> optionalFieldWithDefault -- An optional key with default _may_ in the file, the default will be used otherwise
--               "port"
--               8000
--               "The post to host the server at."
--           <*> requiredField -- A required field must be in the file
--               "token"
--               "The authorisation token that clients can use to authenticate themselves."
--
-- -- Now you've already documented the configuration in code. This will -- make sure that your documentation stays correct because it will be -- type-checked. -- -- Now you can implement FromJSON like so: -- -- 
--   instance FromJSON Configuration where
--     parseJSON = viaYamlSchema
--
-- -- And you can get user-facing documentation about the format for free -- using 'prettySchema . explainParser': -- -- 
--   # Configuration
--   url: # optional
--     # The url to host the server at. It will be hosted on 'localhost' by default.
--     <string>
--   port: # optional, default: 8000
--     # The post to host the server at.
--     <number>
--   token: # required
--     # The authorisation token that clients can use to authenticate themselves.
--     <bool>
--
-- -- If you are also using 'optparse-applicative', you can even add this -- documentation to your `--help` page as well using confDesc: -- -- 
--   argParser :: ParserInfo SomethingElse
--   argParser =
--     info
--       (helper <$> parseSomethingElse)
--       (confDesc @Configuration)
--
module YamlParse.Applicative -- | A class of types for which a schema is defined. -- -- Note that you do not have to use this class and can just use your own -- parser values. Note also that the parsing of a type of this class -- should correspond to the parsing of the type in the FromJSON class. class YamlSchema a -- | A yamlschema for one value -- -- See the sections on helper functions for implementing this for plenty -- of examples. yamlSchema :: YamlSchema a => YamlParser a -- | A yamlschema for a list of values -- -- This is really only useful for cases like Char and -- String yamlSchemaList :: YamlSchema a => YamlParser [a] -- | A class of types for which a schema for keys is defined. class YamlKeySchema a yamlKeySchema :: YamlKeySchema a => KeyParser a -- | Declare a parser of a named object objectParser :: Text -> ObjectParser o -> YamlParser o -- | Declare a parser of an unnamed object -- -- Prefer objectParser if you can. unnamedObjectParser :: ObjectParser o -> YamlParser o -- | Make a parser that parses a value using the given extra parsing -- function -- -- You can use this to make a parser for a type with a smart constructor. -- Prefer eitherParser if you can so you get better error -- messages. -- -- Example: -- -- 
--   parseUsername :: Text -> Maybe Username
--   
--   instance YamlSchema Username where
--     yamlSchema = maybeParser parseUsername yamlSchema
--
maybeParser :: Show o => (o -> Maybe u) -> Parser i o -> Parser i u -- | Make a parser that parses a value using the given extra parsing -- function -- -- You can use this to make a parser for a type with a smart constructor. -- If you don't have a Show instance for your o, then you -- can use extraParser instead. -- -- Example: -- -- 
--   parseUsername :: Text -> Either String Username
--   
--   instance YamlSchema Username where
--     yamlSchema = eitherParser parseUsername yamlSchema
--
eitherParser :: Show o => (o -> Either String u) -> Parser i o -> Parser i u -- | Make a parser that parses a value using the given extra parsing -- function -- -- You can use this to make a parser for a type with a smart constructor. -- Prefer eitherParser if you can, use this if you don't have a -- Show instance for your o. extraParser :: (o -> Parser u) -> Parser i o -> Parser i u -- | Add a comment to a parser -- -- This info will be used in the schema for documentation. -- -- For example: -- -- 
--   data Result = Error | Ok
--   instance YamlSchema Result where
--     yamlSchema = alternatives
--       [ Error <$ literalString "Error" <?> "An error"
--       , Ok <$ literalString "Ok" <?> "Oll Klear"
--       ]
--
() :: Parser i a -> Text -> Parser i a -- | Add a list of lines of comments to a parser -- -- This info will be used in the schema for documentation. -- -- For example: -- -- 
--   data Result = Error | Ok
--   instance YamlSchema Result where
--     yamlSchema = alternatives
--       [ Error <$ literalString "Error" <??> ["Just an error", "but I've got a lot to say about this"]
--       , Ok <$ literalString "Ok" <??> ["Oll Klear", "I really don't know where 'OK' comes from?!"]
--       ]
--
() :: Parser i a -> [Text] -> Parser i a -- | A parser for a required field in an object at a given key requiredField :: YamlSchema a => Text -> Text -> ObjectParser a -- | A parser for a required field in an object at a given key without a -- help text requiredField' :: YamlSchema a => Text -> ObjectParser a -- | A parser for a required field at a given key with a parser for what is -- found at that key requiredFieldWith :: Text -> Text -> YamlParser a -> ObjectParser a -- | A parser for a required field at a given key with a parser for what is -- found at that key without a help text requiredFieldWith' :: Text -> YamlParser a -> ObjectParser a -- | A parser for an optional field in an object at a given key optionalField :: YamlSchema a => Text -> Text -> ObjectParser (Maybe a) -- | A parser for an optional field in an object at a given key without a -- help text optionalField' :: YamlSchema a => Text -> ObjectParser (Maybe a) -- | A parser for an optional field at a given key with a parser for what -- is found at that key optionalFieldWith :: Text -> Text -> YamlParser a -> ObjectParser (Maybe a) -- | A parser for an optional field at a given key with a parser for what -- is found at that key without a help text optionalFieldWith' :: Text -> YamlParser a -> ObjectParser (Maybe a) -- | A parser for an optional field in an object at a given key with a -- default value optionalFieldWithDefault :: (Show a, YamlSchema a) => Text -> a -> Text -> ObjectParser a -- | A parser for an optional field in an object at a given key with a -- default value without a help text optionalFieldWithDefault' :: (Show a, YamlSchema a) => Text -> a -> ObjectParser a -- | A parser for an optional field at a given key with a default value and -- a parser for what is found at that key -- -- For the sake of documentation, the default value needs to be showable. optionalFieldWithDefaultWith :: Show a => Text -> a -> Text -> YamlParser a -> ObjectParser a -- | A parser for an optional field at a given key with a default value and -- a parser for what is found at that key without a help text -- -- For the sake of documentation, the default value needs to be showable. optionalFieldWithDefaultWith' :: Show a => Text -> a -> YamlParser a -> ObjectParser a -- | Parse a string-like thing by Read-ing it -- -- You probably don't want to use Read. viaRead :: Read a => YamlParser a -- | Declare a parser for an exact string. -- -- You can use this to parse a constructor in an enum for example: -- -- 
--   data Fruit = Apple | Banana
--   
--   instance YamlSchema Fruit where
--     yamlSchema = Apple <$ literalString "Apple" <|> Banana <$ literalString "Banana"
--
literalString :: Text -> YamlParser Text -- | Declare a parser for a value using its show instance -- -- Note that no value is read. The parsed string is just compared to the -- shown given value. -- -- You can use this to parse a constructor in an enum when it has a -- ToJSON instance. -- -- For example -- -- 
--   data Fruit = Apple | Banana | Melon
--     deriving (Eq, Generic)
--   
--   instance ToJSON Fruit
--   
--   instance YamlSchema Fruit where
--     yamlSchema = alternatives
--        [ literalValue Apple
--        , literalValue Banana
--        , literalValue Melon
--        ]
--
literalValue :: ToJSON a => a -> YamlParser a -- | Declare a parser for a value using its show instance -- -- Note that no value is read. The parsed string is just compared to the -- shown given value. -- -- You can use this to parse a constructor in an enum when it has a -- Show instance. -- -- For example: -- -- 
--   data Fruit = Apple | Banana | Melon
--     deriving (Show, Eq)
--   
--   instance YamlSchema Fruit where
--     yamlSchema = alternatives
--        [ literalShowString Apple
--        , literalShowString Banana
--        , literalShowString Melon
--        ]
--
literalShowValue :: Show a => a -> YamlParser a -- | Use the first parser of the given list that succeeds -- -- You can use this to parse a constructor in an enum. -- -- For example: -- -- 
--   data Fruit = Apple | Banana | Melon
--   
--   instance YamlSchema Fruit where
--     yamlSchema = alternatives
--        [ Apple <$ literalString "Apple"
--        , Banana <$ literalString "Banana"
--        , Melon <$ literalString "Melon"
--        ]
--
alternatives :: [Parser i o] -> Parser i o type YamlParser a = Parser Value a type ObjectParser a = Parser Object a -- | A parser that takes values of type i as input and parses them -- into values of type o -- -- Note that there is no Monad instance. data Parser i o -- | Return the input [ParseAny] :: Parser i i -- | Parse via an extra parsing function [ParseExtra] :: (o -> Parser u) -> Parser i o -> Parser i u -- | Match an exact value [ParseEq] :: (Show o, Eq o) => o -> Text -> Parser i o -> Parser i o -- | Parse null only. [ParseNull] :: Parser Value () -- | Parse null as Nothing and the rest as Just. [ParseMaybe] :: Parser Value o -> Parser Value (Maybe o) -- | Parse a boolean value [ParseBool] :: Maybe Text -> Parser Bool o -> Parser Value o -- | Parse a String value [ParseString] :: Maybe Text -> Parser Text o -> Parser Value o -- | Parse a numeric value [ParseNumber] :: Maybe Text -> Parser Scientific o -> Parser Value o -- | Parse an array [ParseArray] :: Maybe Text -> Parser Array o -> Parser Value o -- | Parse an object [ParseObject] :: Maybe Text -> Parser Object a -> Parser Value a -- | Parse a list of elements all in the same way [ParseList] :: Parser Value o -> Parser Array (Vector o) -- | Parse a map where the keys are the yaml keys [ParseMap] :: Parser Value v -> Parser Object (HashMap Text v) -- | Parse a map's keys via a given parser [ParseMapKeys] :: Ord k => Parser Text k -> Parser Object (HashMap Text v) -> Parser Object (Map k v) -- | Parse a field of an object [ParseField] :: Text -> FieldParser o -> Parser Object o -- | A pure value [ParsePure] :: a -> Parser i a -- | To implement Functor [ParseFmap] :: (a -> b) -> Parser i a -> Parser i b -- | To implement Applicative [ParseAp] :: Parser i (a -> b) -> Parser i a -> Parser i b -- | To implement Alternative [ParseAlt] :: [Parser i o] -> Parser i o -- | Add comments to the parser. This info will be used in the schema for -- documentation. [ParseComment] :: Text -> Parser i o -> Parser i o data FieldParser o [FieldParserFmap] :: (a -> b) -> FieldParser a -> FieldParser b [FieldParserRequired] :: YamlParser o -> FieldParser o [FieldParserOptional] :: YamlParser o -> FieldParser (Maybe o) [FieldParserOptionalWithDefault] :: Show o => YamlParser o -> o -> FieldParser o -- | Helper function to implement FromJSON via YamlSchema -- -- Example: -- -- 
--   instance FromJSON Config where
--     parseJSON = viaYamlSchema
--
viaYamlSchema :: YamlSchema a => Value -> Parser a -- | A helper newtype to parse a yaml value using the YamlSchema parser. -- -- Example: -- -- 
--   case Data.Yaml.decodeEither' contents of
--     Left e -> die $ show e
--     Right (ViaYamlSchema res) -> print res
--
-- -- This only helps you when you really don't want to implement a -- FromJSON instance. See viaYamlSchema if you do. newtype ViaYamlSchema a ViaYamlSchema :: a -> ViaYamlSchema a -- | Use a Parser to parse a value from Yaml. -- -- A 'Parser i o' corresponds exactly to a 'i -> Yaml.Parser o' and -- this function servers as evidence for that. implementParser :: Parser i o -> i -> Parser o -- | Render pretty documentation about the yamlSchema of a type -- -- This is meant for humans. The output may look like YAML but it is not. prettySchemaDoc :: forall a. YamlSchema a => Text -- | Render pretty documentation about a parser -- -- This is meant for humans. The output may look like YAML but it is not. prettyParserDoc :: Parser i o -> Text -- | Render pretty colourised documentation about the yamlSchema of -- a type -- -- This is meant for humans. The output may look like YAML but it is not. prettyColourisedSchemaDoc :: forall a. YamlSchema a => Text -- | Render pretty colourised documentation about a parser -- -- This is meant for humans. The output may look like YAML but it is not. prettyColourisedParserDoc :: Parser i o -> Text -- | Use a parser to produce a schema that describes it for documentation. -- -- Nothing means that nothing even needs to be parsed, you just get the -- a without parsing anything. This is for the pure case. explainParser :: Parser i o -> Schema data Schema EmptySchema :: Schema AnySchema :: Schema ExactSchema :: Text -> Schema NullSchema :: Schema MaybeSchema :: Schema -> Schema BoolSchema :: Maybe Text -> Schema NumberSchema :: Maybe Text -> Schema StringSchema :: Maybe Text -> Schema ArraySchema :: Maybe Text -> Schema -> Schema ObjectSchema :: Maybe Text -> Schema -> Schema FieldSchema :: Text -> Bool -> Maybe Text -> Schema -> Schema ListSchema :: Schema -> Schema MapSchema :: Schema -> Schema MapKeysSchema :: Schema -> Schema ApSchema :: Schema -> Schema -> Schema AltSchema :: [Schema] -> Schema CommentSchema :: Text -> Schema -> Schema -- | Render a schema as pretty text. -- -- This is meant for humans. The output may look like YAML but it is not. prettySchema :: Schema -> Text -- | Render a schema as pretty and colourised text. -- -- This is meant for humans. The output may look like YAML but it is not. prettyColourisedSchema :: Schema -> Text -- | Helper function to add the schema documentation for a -- YamlSchema parser to the optparse applicative help output confDesc :: forall o a. YamlSchema o => InfoMod a -- | Helper function to add the schema documentation for a given parser to -- the optparse applicative help output confDescWith :: Parser i o -> InfoMod a -- | Helper function to read a config file for a type in YamlSchema readConfigFile :: (YamlSchema a, FromJSON a) => Path r File -> IO (Maybe a) -- | Helper function to read the first in a list of config files readFirstConfigFile :: forall a r. (FromJSON a, YamlSchema a) => [Path r File] -> IO (Maybe a)