-- 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.Internal.Data.Data.Data Config.Number.Number
instance GHC.Internal.Data.Data.Data Config.Number.Radix
instance GHC.Classes.Eq Config.Number.Number
instance GHC.Classes.Eq Config.Number.Radix
instance GHC.Internal.Generics.Generic Config.Number.Number
instance GHC.Internal.Generics.Generic Config.Number.Radix
instance GHC.Classes.Ord Config.Number.Number
instance GHC.Classes.Ord Config.Number.Radix
instance GHC.Internal.Read.Read Config.Number.Number
instance GHC.Internal.Read.Read Config.Number.Radix
instance GHC.Internal.Show.Show Config.Number.Number
instance GHC.Internal.Show.Show Config.Number.Radix

-- | 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 (list of key-value pairs)
--   
- Lists
--   
- Text
--   
- Numbers
--   
- Atoms
--   
--   
--   
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
--   
--   
--   
- No prefix for decimal (base 10) integer literals
--   
- Prefix binary (base 2) integer literals with 0b or
--   0B
--   
- Prefix octal (base 8) integer literals with 0o or
--   0O
--   
- Prefix hexadecimal (base 16) integer literals with 0x or
--   0X. Upper and lower-cased hex digits are supported.
--   
--   
--   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 -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> Position
[posIndex] :: Position -> {-# UNPACK #-} !Int
[posLine] :: Position -> {-# UNPACK #-} !Int
[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:
--   
--   
--   
- my-key: my-value is Section _ "my-key"
--   (Atom _ "my-value")
--   
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.Eq Config.ParseError
instance GHC.Internal.Exception.Type.Exception Config.ParseError
instance GHC.Classes.Ord Config.ParseError
instance GHC.Internal.Read.Read Config.ParseError
instance GHC.Internal.Show.Show 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
--   
--   
--   
- $ starts a variable.
--   
- @ starts a directive.
--   
--   
--   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 GHC.Classes.Eq Config.Macro.FilePosition
instance GHC.Classes.Eq Config.Macro.LoadFileError
instance GHC.Classes.Eq a => GHC.Classes.Eq (Config.Macro.MacroError a)
instance GHC.Internal.Exception.Type.Exception Config.Macro.LoadFileError
instance (GHC.Internal.Data.Typeable.Internal.Typeable a, GHC.Internal.Show.Show a) => GHC.Internal.Exception.Type.Exception (Config.Macro.MacroError a)
instance GHC.Internal.Data.Foldable.Foldable Config.Macro.MacroError
instance GHC.Internal.Base.Functor Config.Macro.MacroError
instance GHC.Classes.Ord Config.Macro.FilePosition
instance GHC.Internal.Read.Read Config.Macro.FilePosition
instance GHC.Internal.Read.Read Config.Macro.LoadFileError
instance GHC.Internal.Read.Read a => GHC.Internal.Read.Read (Config.Macro.MacroError a)
instance GHC.Internal.Show.Show Config.Macro.FilePosition
instance GHC.Internal.Show.Show Config.Macro.LoadFileError
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Config.Macro.MacroError a)
instance GHC.Internal.Data.Traversable.Traversable Config.Macro.MacroError
