-- 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.6.2 -- | Optics for compatibility with the lens package module Config.Lens -- | Apply a function to the subsections of the given value when that value -- is a Sections and the subsection name matches the given -- section name key :: Applicative f => Text -> (Value a -> f (Value a)) -> Value a -> f (Value a) -- | Apply a function to the Text contained inside the given -- Value when it is a Text. text :: Applicative f => (Text -> f Text) -> Value a -> f (Value a) -- | Apply a function to the Integer contained inside the given -- Value when it is a Number. number :: Applicative f => (Integer -> f Integer) -> Value a -> f (Value a) -- | Apply a function to the Text contained inside the given -- Value when it is a Text. This traversal is only valid -- if the output atom is a valid atom! atom :: Applicative f => (Atom -> f Atom) -> Value a -> f (Value a) -- | Apply a function to 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) -- | Apply a function to 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) -- | Apply a function to 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) ann :: Functor f => (a -> f 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 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 *. Each -- leading * 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. -- -- 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 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 -- | 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. -- -- The first field of the Number constructor is the based used in -- the concrete syntax of the configuration value. -- -- The Floating constructor stores the coefficient and power-of-10 -- exponent used in the concrete syntax. This allows representing numbers -- that would otherwise overflow a Double. -- -- Value is parameterized over an annotation type indented to be -- used for file position or other application specific information. -- -- Examples: -- -- data Value a -- | lists of key-value pairs Sections :: a -> [Section a] -> Value a -- | integer literal base (2, 8, 10, or 16) and integer value Number :: a -> Int -> Integer -> Value a -- | coef exponent: coef * 10 ^ exponent Floating :: a -> Integer -> Integer -> 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 -- | 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.Exception Config.ParseError