-- 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.3.1


-- | Lenses and traversals for compatibility with the lens package
module Config.Lens

-- | Traversal for the subsections of the given <a>Value</a> when that
--   value is a <a>Sections</a> 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 <a>Value</a> contained inside the given
--   <a>Value</a>.
text :: Applicative f => (Text -> f Text) -> Value a -> f (Value a)

-- | Traversal for the <a>Integer</a> contained inside the given
--   <a>Value</a> when it is a <a>Number</a>.
number :: Applicative f => (Integer -> f Integer) -> Value a -> f (Value a)

-- | Traversal for the <a>Atom</a> contained inside the given <a>Value</a>.
atom :: Applicative f => (Atom -> f Atom) -> Value a -> f (Value a)

-- | Traversal for the [<a>Value</a>] contained inside the given
--   <a>Value</a> when it is a <a>List</a>.
list :: Applicative f => ([Value a] -> f [Value a]) -> Value a -> f (Value a)

-- | Traversal for the <a>Value</a> elements inside the given <a>Value</a>
--   when it is a <a>List</a>.
--   
--   <pre>
--   <a>values</a> = <a>list</a> . <a>traverse</a>
--   </pre>
values :: Applicative f => (Value a -> f (Value a)) -> Value a -> f (Value a)

-- | Traversal for the [<a>Section</a>] contained inside the given
--   <a>Value</a> when it is a <a>Sections</a>.
sections :: Applicative f => ([Section a] -> f [Section a]) -> Value a -> f (Value a)

-- | Lens for the annotation component of a <a>Value</a>
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 <a>Control.Lens.Plated</a>.
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
--   <a>config-schema</a> package. This package helps extract
--   application-specific meaning from a <a>Value</a>, and can also
--   generate documentation for the supported format.
--   
--   The <tt>config-value</tt> format offers a simple, layout-based syntax
--   for specifying configuration information. In addition configuration
--   values can be pretty-printed back into valid concrete syntax.
--   
--   <h1>Example</h1>
--   
--   <pre>
--   -- 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)"
--   </pre>
--   
--   <h1>Syntax</h1>
--   
--   A configuration file should contain a single <i>value</i> 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:
--   
--   <ul>
--   <li>Sections list (list of key-value pairs)</li>
--   <li>Lists</li>
--   <li>Text</li>
--   <li>Numbers</li>
--   <li>Atoms</li>
--   </ul>
--   
--   <h2>Sections list</h2>
--   
--   <pre>
--   KEY: VALUE
--   KEY: VALUE
--   KEY: VALUE
--   </pre>
--   
--   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 <i>atoms</i>. Section names are nonempty sequences starting
--   with an <i>alpha</i> character followed by zero or more <i>alpha</i>,
--   <i>digit</i>, <i>period</i> (.), underscore (_), or dash (-).
--   
--   Section lists can be nested.
--   
--   Section lists can be used inline, without layout, but surrounding them
--   with <tt>{</tt> and <tt>}</tt> and separating the sections with
--   <tt>,</tt>. The empty sections list is specified with <tt>{}</tt>.
--   
--   Examples:
--   
--   <pre>
--   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
--   </pre>
--   
--   <h2>List</h2>
--   
--   <pre>
--   * VALUE
--   * VALUE
--   * VALUE
--   </pre>
--   
--   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 <tt>[</tt> and <tt>]</tt> with elements
--   separated by <tt>,</tt>. The final list element may be terminated with
--   a trailing comma.
--   
--   Example: <tt>[1, 2, 3]</tt>
--   
--   Layout list entries are started with a leading <tt>*</tt>. Each
--   leading <tt>*</tt> 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:
--   
--   <pre>
--   -- 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
--   </pre>
--   
--   <h2>Text</h2>
--   
--   <pre>
--   "quoted string literals"
--   </pre>
--   
--   Text values are specified using the Haskell string literal syntax.
--   
--   Text values are distinct from <i>atoms</i> described below. This
--   allows a configuration file to make a distinction between the atom
--   <tt>default</tt> and the text value <tt>"default"</tt>, for example.
--   
--   For a detailed description of Haskell string literal syntax, see
--   <a>Haskell 2010 2.6 Character and String Literals</a>
--   
--   <h2>Number</h2>
--   
--   <pre>
--   123.456
--   </pre>
--   
--   Numbers can be written with integer and floating-point literals.
--   
--   Prefix numbers with <tt>-</tt> to construct a negative number.
--   
--   Integer literals support alternate base described below.
--   
--   Floating-point literals can specify a power-of-10 exponent.
--   
--   Bases
--   
--   <ul>
--   <li>No prefix for decimal (base 10) integer literals</li>
--   <li>Prefix binary (base 2) integer literals with <tt>0b</tt> or
--   <tt>0B</tt></li>
--   <li>Prefix octal (base 8) integer literals with <tt>0o</tt> or
--   <tt>0O</tt></li>
--   <li>Prefix hexadecimal (base 16) integer literals with <tt>0x</tt> or
--   <tt>0X</tt>. Upper and lower-cased hex digits are supported.</li>
--   </ul>
--   
--   List of examples:
--   
--   <pre>
--   [ 0, 42, -42, 123.45, 6E7, 1e+10, 3.4e-5, 0xfF, 0b101010, -0o77 ]
--   </pre>
--   
--   <h2>Atom</h2>
--   
--   <pre>
--   unquoted-string
--   </pre>
--   
--   <i>Atoms</i> are unquoted strings that are distinct from normal
--   <i>text</i> values. This type is intended to represent enumerations in
--   a configuration file.
--   
--   Atoms are nonempty sequences starting with an <i>alpha</i> character
--   followed by zero or more <i>alpha</i>, <i>digit</i>, <i>period</i>
--   (.), underscore (_), or dash (-).
--   
--   Lexical syntax: <tt>$alpha [$alpha $digit $unidigit \. _ \-]*</tt>
--   
--   List of examples:
--   
--   <pre>
--   [ yes, no, default, MODE-61 ]
--   </pre>
--   
--   <h2>Comments</h2>
--   
--   Comments are valid white-space.
--   
--   An ordinary comment begins with <tt>--</tt> and extends to the
--   following newline.
--   
--   <pre>
--   -- This is a comment
--   </pre>
--   
--   Use pairs of <tt>{-</tt> and <tt>-}</tt> to create comments that can
--   span multiple lines. These comments can be nested.
--   
--   <pre>
--   {- this {- is -}
--          a comment -}
--   </pre>
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 <a>Value</a> 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 <a>Value</a>
--   
--   Example:
--   
--   <ul>
--   <li><tt>my-key: my-value</tt> is <tt><a>Section</a> (<a>Atom</a>
--   "my-key") (<a>Atom</a> "my-value")</tt></li>
--   </ul>
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 <a>Number</a> constructor is the based used in
--   the concrete syntax of the configuration value.
--   
--   The <a>Value</a> constructor stores the coefficient and power-of-10
--   exponent used in the concrete syntax. This allows representing numbers
--   that would otherwise overflow a <a>Double</a>.
--   
--   <a>Value</a> is parameterized over an annotation type indented to be
--   used for file position or other application specific information.
--   
--   Examples:
--   
--   <ul>
--   <li><tt>0xff</tt> is <tt><a>Number</a> 16 255</tt></li>
--   <li><tt>123</tt> is <tt><a>Number</a> 10 123</tt></li>
--   <li><tt>123e10</tt> is <tt><a>Value</a> 123 10</tt></li>
--   <li><tt>123.45</tt> is <tt><a>Value</a> 12345 (-2)</tt></li>
--   </ul>
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 <a>Atom</a> from <a>Value</a> by type in a
--   configuration. Atoms can be constructed using the
--   <tt>OverloadedStrings</tt> 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.Type.Exception Config.ParseError
