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


-- | 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: <a>numberToRational</a>, <a>numberToInteger</a>,
--   <a>rationalToNumber</a>, or <a>integerToNumber</a>.
--   
--   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 <a>Integer</a>. This representation allows
--   concerned programs to check bounds before converting to a
--   representation like <a>Integer</a>.
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 <a>Rational</a>. Warning: This can use a lot of
--   member in the case of very large exponent parts.
numberToRational :: Number -> Rational

-- | Convert a number to a <a>Integer</a>. Warning: This can use a lot of
--   member in the case of very large exponent parts.
numberToInteger :: Number -> Maybe Integer

-- | <a>Integer</a> to a radix 10 <a>Number</a> with no exponent
integerToNumber :: Integer -> Number

-- | <a>Rational</a> to a radix 10 <a>Number</a> with no exponent
rationalToNumber :: Rational -> Number
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
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


-- | 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>Text</a> contained inside the given <a>Value</a>.
text :: Applicative f => (Text -> f Text) -> 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>Number</a> contained inside the given
--   <a>Value</a>.
number :: Applicative f => (Number -> f Number) -> 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.
--   
--   <a>Value</a> is parameterized over an annotation type indented to be
--   used for file position or other application specific information. When
--   no annotations are needed, <tt>()</tt> 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 <a>Atom</a> from <a>Text</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

-- | 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: <a>numberToRational</a>, <a>numberToInteger</a>,
--   <a>rationalToNumber</a>, or <a>integerToNumber</a>.
--   
--   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 <a>Integer</a>. This representation allows
--   concerned programs to check bounds before converting to a
--   representation like <a>Integer</a>.
data Number

-- | Convert a number to a <a>Integer</a>. Warning: This can use a lot of
--   member in the case of very large exponent parts.
numberToInteger :: Number -> Maybe Integer

-- | Convert a number to a <a>Rational</a>. Warning: This can use a lot of
--   member in the case of very large exponent parts.
numberToRational :: Number -> Rational

-- | <a>Integer</a> to a radix 10 <a>Number</a> with no exponent
integerToNumber :: Integer -> Number

-- | <a>Rational</a> to a radix 10 <a>Number</a> 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
