-- 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: <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
--   memory 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
--   memory 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.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 <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>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>.
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>, <tt>$</tt> or <tt>@</tt> 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>, <tt>+</tt>,
--   or <tt>-</tt>. 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:
--   
--   <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>,
--   <tt>$</tt>, or <tt>@</tt> 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

-- | Pretty-printer that uses no layout for sections or lists.
prettyInline :: 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> _ "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>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

-- | 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
--   memory 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
--   memory 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


-- | This module provides assigns meaning to atoms and section names that
--   start with <tt>@</tt> and <tt>$</tt>. It provides processing pass for
--   configuration to use local variables and inclusion to better structure
--   configuration.
--   
--   <h1>Sigils</h1>
--   
--   <ul>
--   <li><tt>$</tt> starts a variable.</li>
--   <li><tt>@</tt> starts a directive.</li>
--   </ul>
--   
--   Merge key-value mappings using <tt>@splice</tt>.
--   
--   Load external configuration with <tt>@load</tt>.
--   
--   <h1>Variables</h1>
--   
--   Variables are atoms that start with a <tt>$</tt> 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.
--   
--   <pre>
--   $example: 42
--   field1: $example
--   field2: [0, $example]
--   </pre>
--   
--   expands to
--   
--   <pre>
--   field1: 42
--   field2: [0, 42]
--   </pre>
--   
--   Later variable definitions will shadow earlier definitions.
--   
--   <pre>
--   { $x: 1, $x: 2, k: $x }
--   </pre>
--   
--   expands to
--   
--   <pre>
--   { k: 2 }
--   </pre>
--   
--   Scoping examples:
--   
--   <pre>
--   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
--   </pre>
--   
--   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:
--   
--   <pre>
--   $x: 1
--   $y: $x -- OK, y is now 1
--   </pre>
--   
--   Not allowed:
--   
--   <pre>
--   $y: $x -- BAD: $x was not in scope
--   $x: 1
--   z:  $y
--   </pre>
--   
--   <h1>Sections splicing</h1>
--   
--   One sections value can be spliced into another sections value using
--   the <tt>@splice</tt> directive. It is an error to splice a value that
--   is not a key-value sections.
--   
--   <pre>
--   $xy: { x: 0, y: 1 }
--   example:
--     @splice: $xy
--     z: 2
--   </pre>
--   
--   expands to
--   
--   <pre>
--   example:
--     x: 0
--     y: 1
--     z: 2
--   </pre>
--   
--   <h1>File loading</h1>
--   
--   The <tt>@load</tt> directive is intended including configuration from
--   other sources. <a>loadFileWithMacros</a> provides an interpretation of
--   this directive that loads other files. An arbitrary interpretation can
--   be defined with <a>expandMacros'</a>
--   
--   To load a value define a key-value mapping with a single
--   <tt>@load</tt> key with a value specifying the location to load from.
--   
--   <pre>
--   x: @load: "fourty-two.cfg"
--   </pre>
--   
--   could expand to
--   
--   <pre>
--   x: 42
--   </pre>
module Config.Macro

-- | Errors from macro expansion annotated with the <a>valueAnn</a> from
--   the <a>Value</a> 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 <tt>@splice</tt>
BadSplice :: a -> MacroError a

-- | Incorrect use of <tt>@load</tt>
BadLoad :: a -> MacroError a

-- | Expand macros in a configuration value.
--   
--   <tt>@load</tt> not supported and results in a <a>BadLoad</a> 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 <a>loadFileWithMacros</a>
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.
--   
--   <tt>@load</tt> will compute included file path from the given function
--   given the load argument and current configuration file path.
--   
--   Valid <tt>@load</tt> arguments are string literals use as arguments to
--   the path resolution function.
--   
--   Throws <a>IOError</a> from file loads and <a>LoadFileError</a>
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)
