-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Simple, layout-based value language similar to YAML or JSON -- -- This package implements a language similar to YAML or JSON but with -- fewer special cases and fewer dependencies. It emphasizes layout -- structure for sections and lists, and requires quotes around strings. @package config-value @version 0.8.3 -- | This module provides a representation of numbers in scientific -- notation. module Config.Number -- | Numbers are represented as base, coefficient, and exponent. -- -- The most convenient way to get numbers into and out of this form is to -- use one of: numberToRational, numberToInteger, -- rationalToNumber, or integerToNumber. -- -- This representation is explicit about the radix and exponent used to -- facilitate better pretty-printing. By using explicit exponents -- extremely large numbers can be represented compactly. Consider that it -- is easy to write `1e100000000` which would use a significant amount of -- memory if realized as an Integer. This representation allows -- concerned programs to check bounds before converting to a -- representation like Integer. data Number MkNumber :: !Radix -> !Rational -> Number [numberRadix] :: Number -> !Radix [numberCoefficient] :: Number -> !Rational -- | Radix used for a number. Some radix modes support an exponent. data Radix -- | binary, base 2 Radix2 :: Radix -- | octal, base 8 Radix8 :: Radix -- | decimal, base 10, exponent base 10 Radix10 :: !Integer -> Radix -- | hexdecimal, base 16, exponent base 2 Radix16 :: !Integer -> Radix -- | Returns the radix as an integer ignoring any exponent. radixToInt :: Radix -> Int -- | Convert a number to a Rational. Warning: This can use a lot of -- memory in the case of very large exponent parts. numberToRational :: Number -> Rational -- | Convert a number to a Integer. Warning: This can use a lot of -- memory in the case of very large exponent parts. numberToInteger :: Number -> Maybe Integer -- | Integer to a radix 10 Number with no exponent integerToNumber :: Integer -> Number -- | Rational to a radix 10 Number with no exponent rationalToNumber :: Rational -> Number instance GHC.Generics.Generic Config.Number.Radix instance Data.Data.Data Config.Number.Radix instance GHC.Show.Show Config.Number.Radix instance GHC.Read.Read Config.Number.Radix instance GHC.Classes.Ord Config.Number.Radix instance GHC.Classes.Eq Config.Number.Radix instance GHC.Generics.Generic Config.Number.Number instance Data.Data.Data Config.Number.Number instance GHC.Show.Show Config.Number.Number instance GHC.Read.Read Config.Number.Number instance GHC.Classes.Ord Config.Number.Number instance GHC.Classes.Eq Config.Number.Number -- | Lenses and traversals for compatibility with the lens package module Config.Lens -- | Traversal for the subsections of the given Value when that -- value is a Sections and the section name matches the given -- name. key :: Applicative f => Text -> (Value a -> f (Value a)) -> Value a -> f (Value a) -- | Traversal for the Text contained inside the given Value. text :: Applicative f => (Text -> f Text) -> Value a -> f (Value a) -- | Traversal for the Atom contained inside the given Value. atom :: Applicative f => (Atom -> f Atom) -> Value a -> f (Value a) -- | Traversal for the Number contained inside the given -- Value. number :: Applicative f => (Number -> f Number) -> Value a -> f (Value a) -- | Traversal for the [Value] contained inside the given -- Value when it is a List. list :: Applicative f => ([Value a] -> f [Value a]) -> Value a -> f (Value a) -- | Traversal for the Value elements inside the given Value -- when it is a List. -- -- 
--   values = list . traverse
--
values :: Applicative f => (Value a -> f (Value a)) -> Value a -> f (Value a) -- | Traversal for the [Section] contained inside the given -- Value when it is a Sections. sections :: Applicative f => ([Section a] -> f [Section a]) -> Value a -> f (Value a) -- | Lens for the annotation component of a Value ann :: Functor f => (a -> f a) -> Value a -> f (Value a) -- | Traversal for the immediate values in a list or a sections list. -- -- This is intended to be used with Control.Lens.Plated. valuePlate :: Applicative f => (Value a -> f (Value a)) -> Value a -> f (Value a) -- | This module parses files using the syntax demonstrated below. The full -- lexical syntax is available in the Alex source file. The full grammar -- is available in the Happy source file. -- -- Configuration file schemas can be specified using the -- config-schema package. This package helps extract -- application-specific meaning from a Value, and can also -- generate documentation for the supported format. -- -- The config-value format offers a simple, layout-based syntax -- for specifying configuration information. In addition configuration -- values can be pretty-printed back into valid concrete syntax. -- --

Example

-- -- 
--   -- Line comments until newline
--   layout:
--     based:
--       configuration:
--         {} -- empty section
--   
--       sections:
--        "glguy"
--   
--       {- Block comments
--          {- nested comments -}
--          "O'caml style {- strings in comments"
--          so you can comment out otherwise valid
--          portions of your config
--       -}
--       atoms      : yes
--   
--       decimal    : -1234
--       hexadecimal: 0x1234
--       octal      : 0o1234
--       binary     : 0b1010
--   
--   lists:
--      * sections: in-lists
--        next-section: still-in-list
--      * [ "inline", "lists" ]
--      * * "nestable"
--        * "layout"
--        * "lists"
--      * 3
--   
--   unicode : "standard Haskell format strings (1 ≤ 2)\x2228(2 ≤ 3)"
--
-- --

Syntax

-- -- A configuration file should contain a single value at the -- top-level. Typically this value will be a list of sections (as seen in -- the example above). -- -- Unicode character classes are fully supported. The alpha and digit -- character classes use the full Unicode range, rather than merely the -- ASCII ranges. -- -- There are 5 distinct types of values possible in a configuration file: -- -- -- --

Sections list

-- -- 
--   KEY: VALUE
--   KEY: VALUE
--   KEY: VALUE
--
-- -- Sections lists are lists of key-value pairs. Each key in the list -- should start on the same column in the file. The value of the pair -- should be indented to the right of the key. -- -- The lexical syntax for section names is identical to the lexical -- syntax of atoms. Section names are nonempty sequences starting -- with an alpha, $ or @ character followed by -- zero or more alpha, digit, period (.), underscore -- (_), or dash (-). -- -- Section lists can be nested. -- -- Section lists can be used inline, without layout, but surrounding them -- with { and } and separating the sections with -- ,. The empty sections list is specified with {}. -- -- Examples: -- -- 
--   key-1 : -- spaces are allowed between the section name and the colon
--     key-1.1: value-1.1
--     key-1.2: [ value-1.2 ]
--   key-2: value-2
--   key-3: {} -- the value for key-3 is the empty sections list
--   key-4: { red: 1, blue: 2} -- inline syntax for sublist
--
-- --

List

-- -- 
--   * VALUE
--   * VALUE
--   * VALUE
--
-- -- Lists can be specified using either layout or inline syntax. There is -- no distinction between the two syntaxes in the abstract syntax. -- -- Inline lists are surrounded by [ and ] with elements -- separated by ,. The final list element may be terminated with -- a trailing comma. -- -- Example: [1, 2, 3] -- -- Layout list entries are started with a leading *, +, -- or -. Each leading bullet must occur in the some column of -- the file. Lists can be nested by starting the new list on a column to -- the right of the current list. A single list must use the same bullet -- token for every element of the list. Nested lists can choose a -- different bullet. This can help visually distinguish nested lists. -- -- Layout based lists can not occur inside inline list syntax. Layout -- based section lists can occur inside layout based lists -- -- Example: -- -- 
--   -- One list element containing an atom
--   * item-1
--   
--   -- One list element containing a two element list
--   * * item-2.1
--     * item-2.2
--   
--   -- One list element containing two key-value pairs
--   * key-1: value-1
--     key-2: value-2
--
-- --

Text

-- -- 
--   "quoted string literals"
--
-- -- Text values are specified using the Haskell string literal syntax. -- -- Text values are distinct from atoms described below. This -- allows a configuration file to make a distinction between the atom -- default and the text value "default", for example. -- -- For a detailed description of Haskell string literal syntax, see -- Haskell 2010 2.6 Character and String Literals -- --

Number

-- -- 
--   123.456
--
-- -- Numbers can be written with integer and floating-point literals. -- -- Prefix numbers with - to construct a negative number. -- -- Integer literals support alternate base described below. -- -- Floating-point literals can specify a power-of-10 exponent. -- -- Bases -- -- -- -- List of examples: -- -- 
--   [ 0, 42, -42, 123.45, 6E7, 1e+10, 3.4e-5, 0xfF, 0b101010, -0o77 ]
--
-- --

Atom

-- -- 
--   unquoted-string
--
-- -- Atoms are unquoted strings that are distinct from normal -- text values. This type is intended to represent enumerations in -- a configuration file. -- -- Atoms are nonempty sequences starting with an alpha, -- $, or @ character followed by zero or more -- alpha, digit, period (.), underscore (_), or dash -- (-). -- -- Lexical syntax: $alpha [$alpha $digit $unidigit \. _ \-]* -- -- List of examples: -- -- 
--   [ yes, no, default, MODE-61 ]
--
-- --

Comments

-- -- Comments are valid white-space. -- -- An ordinary comment begins with -- and extends to the -- following newline. -- -- 
--   -- This is a comment
--
-- -- Use pairs of {- and -} to create comments that can -- span multiple lines. These comments can be nested. -- -- 
--   {- this {- is -}
--          a comment -}
--
module Config -- | Parse a configuration file and return the result on the right, or the -- position of an error on the left. -- -- The resulting value is annotated with source file locations. -- -- Note: Text file lines are terminated by new-lines. parse :: Text -> Either ParseError (Value Position) -- | A position in a text file data Position Position :: {-# UNPACK #-} !Int -> Position [posIndex, posLine, posColumn] :: Position -> {-# UNPACK #-} !Int -- | Pretty-print a Value as shown in the example. Sections will -- nest complex values underneath with indentation and simple values will -- be rendered on the same line as their section. pretty :: Value a -> Doc -- | Pretty-printer that uses no layout for sections or lists. prettyInline :: Value a -> Doc -- | A single section of a Value -- -- Example: -- -- data Section a Section :: a -> Text -> Value a -> Section a [sectionAnn] :: Section a -> a [sectionName] :: Section a -> Text [sectionValue] :: Section a -> Value a -- | Sum type of the values supported by this language. -- -- Value is parameterized over an annotation type indented to be -- used for file position or other application specific information. When -- no annotations are needed, () is a fine choice. data Value a -- | lists of key-value pairs Sections :: a -> [Section a] -> Value a -- | numbers Number :: a -> Number -> Value a -- | quoted strings Text :: a -> Text -> Value a -- | unquoted strings Atom :: a -> Atom -> Value a -- | lists List :: a -> [Value a] -> Value a -- | Wrapper to distinguish Atom from Text by type in a -- configuration. Atoms can be constructed using the -- OverloadedStrings extension. newtype Atom MkAtom :: Text -> Atom [atomName] :: Atom -> Text -- | Returns the annotation for a value. valueAnn :: Value a -> a -- | Numbers are represented as base, coefficient, and exponent. -- -- The most convenient way to get numbers into and out of this form is to -- use one of: numberToRational, numberToInteger, -- rationalToNumber, or integerToNumber. -- -- This representation is explicit about the radix and exponent used to -- facilitate better pretty-printing. By using explicit exponents -- extremely large numbers can be represented compactly. Consider that it -- is easy to write `1e100000000` which would use a significant amount of -- memory if realized as an Integer. This representation allows -- concerned programs to check bounds before converting to a -- representation like Integer. data Number -- | Convert a number to a Integer. Warning: This can use a lot of -- memory in the case of very large exponent parts. numberToInteger :: Number -> Maybe Integer -- | Convert a number to a Rational. Warning: This can use a lot of -- memory in the case of very large exponent parts. numberToRational :: Number -> Rational -- | Integer to a radix 10 Number with no exponent integerToNumber :: Integer -> Number -- | Rational to a radix 10 Number with no exponent rationalToNumber :: Rational -> Number -- | Error messages that can occur during parsing annotated with a file -- position. data ParseError ParseError :: Position -> String -> ParseError instance GHC.Classes.Ord Config.ParseError instance GHC.Classes.Eq Config.ParseError instance GHC.Show.Show Config.ParseError instance GHC.Read.Read Config.ParseError instance GHC.Exception.Type.Exception Config.ParseError -- | This module provides assigns meaning to atoms and section names that -- start with @ and $. It provides processing pass for -- configuration to use local variables and inclusion to better structure -- configuration. -- --

Sigils

-- -- -- -- Merge key-value mappings using @splice. -- -- Load external configuration with @load. -- --

Variables

-- -- Variables are atoms that start with a $ sigil. Variables are -- defined by setting a variable as a section name. This variable will -- remain in scope for the remainder of the sections being defined. -- -- Variables used in a value position will be replaced with their -- previously defined values. -- -- 
--   $example: 42
--   field1: $example
--   field2: [0, $example]
--
-- -- expands to -- -- 
--   field1: 42
--   field2: [0, 42]
--
-- -- Later variable definitions will shadow earlier definitions. -- -- 
--   { $x: 1, $x: 2, k: $x }
--
-- -- expands to -- -- 
--   { k: 2 }
--
-- -- Scoping examples: -- -- 
--   top1:
--     a:  $x                     -- BAD: $x not defined yet
--     $x: 42                     -- $x is now defined to be 42
--     b:  $x                     -- OK: $x was defined above
--     c:  {sub1: $x, sub2: [$x]} -- OK: $x in scope in subsections
--                                -- note: $x now goes out of scope
--   top2: $x                     -- BAD: $x no longer in scope
--
-- -- Macros are expanded at their definition site. All variables are -- resolved before adding the new variable into the environment. -- Variables are lexically scoped rather than dynamically scoped. -- -- Allowed: -- -- 
--   $x: 1
--   $y: $x -- OK, y is now 1
--
-- -- Not allowed: -- -- 
--   $y: $x -- BAD: $x was not in scope
--   $x: 1
--   z:  $y
--
-- --

Sections splicing

-- -- One sections value can be spliced into another sections value using -- the @splice directive. It is an error to splice a value that -- is not a key-value sections. -- -- 
--   $xy: { x: 0, y: 1 }
--   example:
--     @splice: $xy
--     z: 2
--
-- -- expands to -- -- 
--   example:
--     x: 0
--     y: 1
--     z: 2
--
-- --

File loading

-- -- The @load directive is intended including configuration from -- other sources. loadFileWithMacros provides an interpretation of -- this directive that loads other files. An arbitrary interpretation can -- be defined with expandMacros' -- -- To load a value define a key-value mapping with a single -- @load key with a value specifying the location to load from. -- -- 
--   x: @load: "fourty-two.cfg"
--
-- -- could expand to -- -- 
--   x: 42
--
module Config.Macro -- | Errors from macro expansion annotated with the valueAnn from -- the Value nearest to the problem (typically a file position). data MacroError a -- | Variable used before its defintion UndeclaredVariable :: a -> Text -> MacroError a -- | Unknown directive UnknownDirective :: a -> Text -> MacroError a -- | Incorrect use of @splice BadSplice :: a -> MacroError a -- | Incorrect use of @load BadLoad :: a -> MacroError a -- | Expand macros in a configuration value. -- -- @load not supported and results in a BadLoad error. expandMacros :: Value a -> Either (MacroError a) (Value a) -- | Expand macros in a configuration value using a pre-populated -- environment. expandMacros' :: Monad m => (forall b. MacroError a -> m b) -> (Value a -> m (Value a)) -> Map Text (Value a) -> Value a -> m (Value a) -- | Errors thrown by loadFileWithMacros data LoadFileError -- | failure to parse a file LoadFileParseError :: FilePath -> ParseError -> LoadFileError -- | failure to expand macros LoadFileMacroError :: MacroError FilePosition -> LoadFileError -- | A pair of filepath and position data FilePosition FilePosition :: FilePath -> Position -> FilePosition -- | Load a configuration value from a given file path. -- -- @load will compute included file path from the given function -- given the load argument and current configuration file path. -- -- Valid @load arguments are string literals use as arguments to -- the path resolution function. -- -- Throws IOError from file loads and LoadFileError loadFileWithMacros :: (Text -> FilePath -> IO FilePath) -> FilePath -> IO (Value FilePosition) instance Data.Traversable.Traversable Config.Macro.MacroError instance Data.Foldable.Foldable Config.Macro.MacroError instance GHC.Base.Functor Config.Macro.MacroError instance GHC.Show.Show a => GHC.Show.Show (Config.Macro.MacroError a) instance GHC.Read.Read a => GHC.Read.Read (Config.Macro.MacroError a) instance GHC.Classes.Eq a => GHC.Classes.Eq (Config.Macro.MacroError a) instance GHC.Classes.Eq Config.Macro.FilePosition instance GHC.Classes.Ord Config.Macro.FilePosition instance GHC.Show.Show Config.Macro.FilePosition instance GHC.Read.Read Config.Macro.FilePosition instance GHC.Show.Show Config.Macro.LoadFileError instance GHC.Read.Read Config.Macro.LoadFileError instance GHC.Classes.Eq Config.Macro.LoadFileError instance GHC.Exception.Type.Exception Config.Macro.LoadFileError instance (Data.Typeable.Internal.Typeable a, GHC.Show.Show a) => GHC.Exception.Type.Exception (Config.Macro.MacroError a)