-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | The <tt>config-ini</tt> library is a set of small monadic languages
--   for writing simple configuration languages with convenient,
--   human-readable error messages.
--   
--   <pre>
--   parseConfig :: IniParser (Text, Int, Bool)
--   parseConfig = section "NETWORK" $ do
--     user &lt;- field        "user"
--     port &lt;- fieldOf      "port" number
--     enc  &lt;- fieldFlagDef "encryption" True
--     return (user, port, enc)
--   </pre>
@package config-ini
@version 0.2.7.0


-- | <b>Warning!</b> This module is subject to change in the future, and
--   therefore should not be relied upon to have a consistent API.
module Data.Ini.Config.Raw

-- | An <tt>Ini</tt> value is a mapping from section names to
--   <a>IniSection</a> values. The section names in this mapping are
--   normalized to lower-case and stripped of whitespace. This sequence
--   retains the ordering of the original source file.
newtype RawIni
RawIni :: Seq (NormalizedText, IniSection) -> RawIni
[fromRawIni] :: RawIni -> Seq (NormalizedText, IniSection)

-- | An <a>IniSection</a> consists of a name, a mapping of key-value pairs,
--   and metadata about where the section starts and ends in the file. The
--   section names found in <a>isName</a> are <b>not</b> normalized to
--   lower-case or stripped of whitespace, and thus should appear exactly
--   as they appear in the original source file.
data IniSection
IniSection :: Text -> Seq (NormalizedText, IniValue) -> Int -> Int -> Seq BlankLine -> IniSection

-- | The name of the section, as it appears in the original INI source
[isName] :: IniSection -> Text

-- | The key-value mapping within that section. Key names here are
--   normalized to lower-case and stripped of whitespace. This sequence
--   retains the ordering of the original source file.
[isVals] :: IniSection -> Seq (NormalizedText, IniValue)

-- | The line on which the section begins. This field is ignored when
--   serializing, and is only used for error messages produced when parsing
--   and deserializing an INI structure.
[isStartLine] :: IniSection -> Int

-- | The line on which the section ends. This field is ignored when
--   serializing, and is only used for error messages produced when parsing
--   and deserializing an INI structure.
[isEndLine] :: IniSection -> Int

-- | The blank lines and comments that appear prior to the section head
--   declaration, retained for pretty-printing identical INI files.
[isComments] :: IniSection -> Seq BlankLine

-- | An <a>IniValue</a> represents a key-value mapping, and also stores the
--   line number where it appears. The key names and values found in
--   <a>vName</a> and <a>vValue</a> respectively are _not_ normalized to
--   lower-case or stripped of whitespace, and thus should appear exactly
--   as they appear in the original source file.
data IniValue
IniValue :: Int -> Text -> Text -> Seq BlankLine -> Bool -> Char -> IniValue

-- | The line on which the key/value mapping appears. This field is ignored
--   when serializing, and is only used for error messages produced when
--   parsing and deserializing an INI structure.
[vLineNo] :: IniValue -> Int

-- | The name of the key, as it appears in the INI source.
[vName] :: IniValue -> Text

-- | The value of the key
[vValue] :: IniValue -> Text
[vComments] :: IniValue -> Seq BlankLine

-- | Right now, this will never show up in a parsed INI file, but it's used
--   when emitting a default INI file: it causes the key-value line to
--   include a leading comment as well.
[vCommentedOut] :: IniValue -> Bool
[vDelimiter] :: IniValue -> Char

-- | We want to keep track of the whitespace/comments in between KV lines,
--   so this allows us to track those lines in a reproducible way.
data BlankLine
CommentLine :: Char -> Text -> BlankLine
BlankLine :: BlankLine

-- | The <a>NormalizedText</a> type is an abstract representation of text
--   which has had leading and trailing whitespace removed and been
--   normalized to lower-case, but from which we can still extract the
--   original, non-normalized version. This acts like the normalized text
--   for the purposes of <a>Eq</a> and <a>Ord</a> operations, so
--   
--   <pre>
--   <a>normalize</a> "  x  " == <a>normalize</a> "X"
--   </pre>
--   
--   This type is used to store section and key names in the
data NormalizedText
NormalizedText :: Text -> Text -> NormalizedText
[actualText] :: NormalizedText -> Text
[normalizedText] :: NormalizedText -> Text

-- | The constructor function to build a <a>NormalizedText</a> value. You
--   probably shouldn't be using this module directly, but if for some
--   reason you are using it, then you should be using this function to
--   create <a>NormalizedText</a> values.
normalize :: Text -> NormalizedText

-- | Parse a <a>Text</a> value into an <tt>Ini</tt> value, retaining a
--   maximal amount of structure as needed to reconstruct the original INI
--   file.
parseRawIni :: Text -> Either String RawIni

-- | Serialize an INI file to text, complete with any comments which appear
--   in the INI structure, and retaining the aesthetic details which are
--   present in the INI file.
printRawIni :: RawIni -> Text

-- | Look up an Ini value by section name and key. Returns the sequence of
--   matches.
lookupInSection :: Text -> Text -> RawIni -> Seq Text

-- | Look up an Ini section by name. Returns a sequence of all matching
--   section records.
lookupSection :: Text -> RawIni -> Seq IniSection

-- | Look up an Ini key's value in a given section by the key. Returns the
--   sequence of matches.
lookupValue :: Text -> IniSection -> Seq IniValue
instance GHC.Classes.Eq Data.Ini.Config.Raw.BlankLine
instance GHC.Classes.Eq Data.Ini.Config.Raw.IniSection
instance GHC.Classes.Eq Data.Ini.Config.Raw.IniValue
instance GHC.Classes.Eq Data.Ini.Config.Raw.NormalizedText
instance GHC.Classes.Eq Data.Ini.Config.Raw.RawIni
instance GHC.Classes.Ord Data.Ini.Config.Raw.NormalizedText
instance GHC.Internal.Show.Show Data.Ini.Config.Raw.BlankLine
instance GHC.Internal.Show.Show Data.Ini.Config.Raw.IniSection
instance GHC.Internal.Show.Show Data.Ini.Config.Raw.IniValue
instance GHC.Internal.Show.Show Data.Ini.Config.Raw.NormalizedText
instance GHC.Internal.Show.Show Data.Ini.Config.Raw.RawIni


-- | This module presents an alternate API for parsing INI files. Unlike
--   the standard API, it is bidirectional: the same declarative structure
--   can be used to parse an INI file to a value, serialize an INI file
--   from a value, or even <i>update</i> an INI file by comparing it
--   against a value and serializing in a way that minimizes the
--   differences between revisions of the file.
--   
--   This API does make some extra assumptions about your configuration
--   type and the way you interact with it: in particular, it assumes that
--   you have lenses for all the fields you're parsing and that you have
--   some kind of sensible default value of that configuration type.
--   Instead of providing combinators which can extract and parse a field
--   of an INI file into a value, the bidirectional API allows you to
--   declaratively associate a lens into your structure with a field of the
--   INI file.
--   
--   Consider the following example INI file:
--   
--   <pre>
--   [NETWORK]
--   host = example.com
--   port = 7878
--   
--   [LOCAL]
--   user = terry
--   </pre>
--   
--   We'd like to parse this INI file into a <tt>Config</tt> type which
--   we've defined like this, using <a>lens</a> or a similar library to
--   provide lenses:
--   
--   <pre>
--   data Config = Config
--     { _cfHost :: String
--     , _cfPort :: Int
--     , _cfUser :: Maybe Text
--     } deriving (Eq, Show)
--   
--   ''makeLenses Config
--   </pre>
--   
--   We can now define a basic specification of the type <tt><a>IniSpec</a>
--   Config ()</tt> by using the provided operations to declare our
--   top-level sections, and then within those sections we can associate
--   fields with <tt>Config</tt> lenses.
--   
--   <pre>
--   <tt>configSpec</tt> :: <a>IniSpec</a> Config ()
--   <tt>configSpec</tt> = do
--     <a>section</a> "NETWORK" $ do
--       cfHost <a>.=</a> <a>field</a> "host" <a>string</a>
--       cfPost <a>.=</a> <a>field</a> "port" <a>number</a>
--     <tt>sectionOpt</tt> "LOCAL" $ do
--       cfUser <a>.=?</a> <a>field</a> "user" <a>text</a>
--   </pre>
--   
--   There are two operators used to associate lenses with fields:
--   
--   <ul>
--   <li><i><a>.=</a></i> Associates a lens of type <tt>Lens' s a</tt> with
--   a field description of type <tt>FieldDescription a</tt>. By default,
--   this will raise an error when parsing if the field described is
--   missing, but we can mark it as optional, as we'll see.</li>
--   <li><i><a>.=?</a></i> Associates a lens of type <tt>Lens' s (Maybe
--   a)</tt> with a field description of type <tt>FieldDescription a</tt>.
--   During parsing, if the value does not appear in an INI file, then the
--   lens will be set to <a>Nothing</a>; similarly, during serializing, if
--   the value is <a>Nothing</a>, then the field will not be serialized in
--   the file.</li>
--   </ul>
--   
--   Each field must include the field's name as well as a
--   <a>FieldValue</a>, which describes how to both parse and serialize a
--   value of a given type. Several built-in <a>FieldValue</a> descriptions
--   are provided, but you can always build your own by providing parsing
--   and serialization functions for individual fields.
--   
--   We can also provide extra metadata about a field, allowing it to be
--   skipped durin parsing, or to provide an explicit default value, or to
--   include an explanatory comment for that value to be used when we
--   serialize an INI file. These are conventionally applied to the field
--   using the <a>&amp;</a> operator:
--   
--   <pre>
--   configSpec :: <a>IniSpec</a> Config ()
--   configSpec = do
--     <a>section</a> "NETWORK" $ do
--       cfHost <a>.=</a> <a>field</a> "host" <a>string</a>
--                   &amp; <a>comment</a> ["The desired hostname (optional)"]
--                   &amp; <a>optional</a>
--       cfPost <a>.=</a> <a>field</a> "port" <a>number</a>
--                   &amp; <a>comment</a> ["The port number"]
--     <tt>sectionOpt</tt> "LOCAL" $ do
--       cfUser <a>.=?</a> <a>field</a> "user" <a>text</a>
--   </pre>
--   
--   When we want to use this specification, we need to create a value of
--   type <a>Ini</a>, which is an abstract representation of an INI
--   specification. To create an <a>Ini</a> value, we need to use the
--   <a>ini</a> function, which combines the spec with the default version
--   of our configuration value.
--   
--   Once we have a value of type <a>Ini</a>, we can use it for three basic
--   operations:
--   
--   <ul>
--   <li>We can parse a textual INI file with <a>parseIni</a>, which will
--   systematically walk the spec and use the provided lens/field
--   associations to create a parsed configuration file. This will give us
--   a new value of type <a>Ini</a> that represents the parsed
--   configuration, and we can extract the actual configuration value with
--   <a>getIniValue</a>.</li>
--   <li>We can update the value contained in an <a>Ini</a> value. If the
--   <a>Ini</a> value is the result of a previous call to <a>parseIni</a>,
--   then this update will attempt to retain as much of the incidental
--   structure of the parsed file as it can: for example, it will attempt
--   to retain comments, whitespace, and ordering. The general strategy is
--   to make the resulting INI file "diff-minimal": the diff between the
--   older INI file and the updated INI file should contain as little noise
--   as possible. Small cosmetic choices such as how to treat generated
--   comments are controlled by a configurable <a>UpdatePolicy</a>
--   value.</li>
--   <li>We can serialize an <a>Ini</a> value to a textual INI file. This
--   will produce the specified INI file (either a default fresh INI, or a
--   modified existing INI) as a textual value.</li>
--   </ul>
module Data.Ini.Config.Bidir

-- | An <a>Ini</a> is an abstract representation of an INI file, including
--   both its textual representation and the Haskell value it represents.
data Ini s

-- | Create a basic <a>Ini</a> value from a default value and a spec.
ini :: s -> IniSpec s () -> Ini s

-- | Get the underlying Haskell value associated with the <a>Ini</a>.
getIniValue :: Ini s -> s

-- | The lens equivalent of <a>getIniValue</a>
iniValueL :: forall s f. Functor f => (s -> f s) -> Ini s -> f (Ini s)

-- | Get the underlying <a>RawIni</a> value for the file.
getRawIni :: Ini s -> RawIni

-- | Parse a textual representation of an <a>Ini</a> file. If the file is
--   malformed or if an obligatory field is not found, this will produce a
--   human-readable error message. If an optional field is not found, then
--   it will fall back on the existing value contained in the provided
--   <a>Ini</a> structure.
parseIni :: Text -> Ini s -> Either String (Ini s)

-- | Get the textual representation of an <a>Ini</a> value. If this
--   <a>Ini</a> value is the result of <a>parseIni</a>, then it will
--   attempt to retain the textual characteristics of the parsed version as
--   much as possible (e.g. by retaining comments, ordering, and whitespace
--   in a way that will minimize the overall diff footprint.) If the
--   <a>Ini</a> value was created directly from a value and a
--   specification, then it will pretty-print an initial version of the
--   file with the comments and placeholder text specified in the spec.
serializeIni :: Ini s -> Text

-- | Update the internal value of an <a>Ini</a> file. If this <a>Ini</a>
--   value is the result of <a>parseIni</a>, then the resulting <a>Ini</a>
--   value will attempt to retain the textual characteristics of the parsed
--   version as much as possible (e.g. by retaining comments, ordering, and
--   whitespace in a way that will minimize the overall diff footprint.)
updateIni :: s -> Ini s -> Ini s

-- | Use the provided <a>UpdatePolicy</a> as a guide when creating future
--   updated versions of the given <a>Ini</a> value.
setIniUpdatePolicy :: UpdatePolicy -> Ini s -> Ini s

-- | An <a>UpdatePolicy</a> guides certain choices made when an <a>Ini</a>
--   file is updated: for example, how to add comments to the generated
--   fields, or how to treat fields which are optional.
data UpdatePolicy
UpdatePolicy :: Bool -> Bool -> UpdateCommentPolicy -> UpdatePolicy

-- | If <a>True</a>, then optional fields not included in the INI file will
--   be included in the updated INI file. Defaults to <a>False</a>.
[updateAddOptionalFields] :: UpdatePolicy -> Bool

-- | If <a>True</a>, then fields in the INI file that have no corresponding
--   description in the <a>IniSpec</a> will be ignored; if <a>False</a>,
--   then those fields will return an error value. Defaults to <a>True</a>.
[updateIgnoreExtraneousFields] :: UpdatePolicy -> Bool

-- | The policy for what to do to comments associated with modified fields
--   during an update. Defaults to <a>CommentPolicyNone</a>.
[updateGeneratedCommentPolicy] :: UpdatePolicy -> UpdateCommentPolicy

-- | An <a>UpdateCommentPolicy</a> describes what comments should accompany
--   a field added to or modified in an existing INI file when using
--   <a>updateIni</a>.
data UpdateCommentPolicy

-- | Do not add comments to new fields
CommentPolicyNone :: UpdateCommentPolicy

-- | Add the same comment which appears in the <a>IniSpec</a> value for the
--   field we're adding or modifying.
CommentPolicyAddFieldComment :: UpdateCommentPolicy

-- | Add a common comment to all new fields added or modified by an
--   <a>updateIni</a> call.
CommentPolicyAddDefaultComment :: Seq Text -> UpdateCommentPolicy

-- | A set of sensible <a>UpdatePolicy</a> defaults which keep the diffs
--   between file versions minimal.
defaultUpdatePolicy :: UpdatePolicy

-- | An <a>IniSpec</a> value represents the structure of an entire
--   INI-format file in a declarative way. The <tt>s</tt> parameter
--   represents the type of a Haskell structure which is being serialized
--   to or from.
data IniSpec s a

-- | A <a>SectionSpec</a> value represents the structure of a single
--   section of an INI-format file in a declarative way. The <tt>s</tt>
--   parameter represents the type of a Haskell structure which is being
--   serialized to or from.
data SectionSpec s a

-- | Define the specification of a top-level INI section.
section :: Text -> SectionSpec s () -> IniSpec s ()

-- | Treat an entire section as containing entirely optional fields.
allOptional :: (SectionSpec s () -> IniSpec s ()) -> SectionSpec s () -> IniSpec s ()

-- | A <a>FieldDescription</a> is a declarative representation of the
--   structure of a field. This includes the name of the field and the
--   <a>FieldValue</a> used to parse and serialize values of that field, as
--   well as other metadata that might be needed in the course of parsing
--   or serializing a structure.
data FieldDescription t

-- | Associate a field description with a field. If this field is not
--   present when parsing, it will attempt to fall back on a default, and
--   if no default value is present, it will fail to parse.
--   
--   When serializing an INI file, this will produce all the comments
--   associated with the field description followed by the value of the
--   field in the.
(.=) :: Eq t => Lens s s t t -> FieldDescription t -> SectionSpec s ()
infixr 0 .=

-- | Associate a field description with a field of type "Maybe a". When
--   parsing, this field will be initialized to <a>Nothing</a> if it is not
--   found, and to a <a>Just</a> value if it is. When serializing an INI
--   file, this will try to serialize a value
(.=?) :: Eq t => Lens s s (Maybe t) (Maybe t) -> FieldDescription t -> SectionSpec s ()
infixr 0 .=?

-- | Create a description of a field by a combination of the name of the
--   field and a <a>FieldValue</a> describing how to parse and emit values
--   associated with that field.
field :: Text -> FieldValue a -> FieldDescription a

-- | Create a description of a <a>Bool</a>-valued field.
flag :: Text -> FieldDescription Bool

-- | Associate a multiline comment with a <a>FieldDescription</a>. When
--   serializing a field that has a comment associated, the comment will
--   appear before the field.
comment :: [Text] -> FieldDescription t -> FieldDescription t

-- | Choose a placeholder value to be displayed for optional fields. This
--   is used when serializing an optional Ini field: the field will appear
--   commented out in the output using the placeholder text as a value, so
--   a spec that includes
--   
--   <pre>
--   myLens .=? field "x" &amp; placeholderValue "&lt;val&gt;"
--   
--   </pre>
--   
--   will serialize into an INI file that contains the line
--   
--   <pre>
--   # x = &lt;val&gt;
--   
--   </pre>
--   
--   A placeholder value will only appear in the serialized output if the
--   field is optional, but will be preferred over serializing the default
--   value for an optional field. This will not affect INI file updates.
placeholderValue :: Text -> FieldDescription t -> FieldDescription t

-- | If the field is not found in parsing, simply skip instead of raising
--   an error or setting anything.
optional :: FieldDescription t -> FieldDescription t

-- | A value of type <a>FieldValue</a> packages up a parser and emitter
--   function into a single value. These are used for bidirectional parsing
--   and emitting of the value of a field.
data FieldValue a
FieldValue :: (Text -> Either String a) -> (a -> Text) -> FieldValue a

-- | The function to use when parsing the value of a field; if the parser
--   fails, then the string will be shown as an error message to the user.
[fvParse] :: FieldValue a -> Text -> Either String a

-- | The function to use when serializing a value into an INI file.
[fvEmit] :: FieldValue a -> a -> Text

-- | Represents a field whose value is a <a>Text</a> value
text :: FieldValue Text

-- | Represents a field whose value is a <a>String</a> value
string :: FieldValue String

-- | Represents a numeric field whose value is parsed according to the
--   <a>Read</a> implementation for that type, and is serialized according
--   to the <a>Show</a> implementation for that type.
number :: (Show a, Read a, Num a, Typeable a) => FieldValue a

-- | Represents a field whose value is a <a>Bool</a> value. This parser is
--   case-insensitive, and matches the words <tt>true</tt>, <tt>false</tt>,
--   <tt>yes</tt>, and <tt>no</tt>, as well as single-letter abbreviations
--   for all of the above. This will serialize as <tt>true</tt> for
--   <a>True</a> and <tt>false</tt> for <a>False</a>.
bool :: FieldValue Bool

-- | A <a>FieldValue</a> for parsing and serializing values according to
--   the logic of the <a>Read</a> and <a>Show</a> instances for that type,
--   providing a convenient human-readable error message if the parsing
--   step fails.
readable :: (Show a, Read a, Typeable a) => FieldValue a

-- | Represents a field whose value is a sequence of other values which are
--   delimited by a given string, and whose individual values are described
--   by another <a>FieldValue</a> value. This uses GHC's <a>IsList</a>
--   typeclass to convert back and forth between sequence types.
listWithSeparator :: IsList l => Text -> FieldValue (Item l) -> FieldValue l

-- | Represents a field whose value is a pair of two other values separated
--   by a given string, whose individual values are described by two
--   different <a>FieldValue</a> values.
pairWithSeparator :: FieldValue l -> Text -> FieldValue r -> FieldValue (l, r)
(&) :: a -> (a -> b) -> b

-- | This is a <a>lens</a>-compatible type alias
type Lens s t a b = forall (f :: Type -> Type). Functor f => a -> f b -> s -> f t
instance GHC.Internal.Base.Applicative (Data.Ini.Config.Bidir.IniSpec s)
instance GHC.Internal.Base.Applicative (Data.Ini.Config.Bidir.SectionSpec s)
instance GHC.Classes.Eq Data.Ini.Config.Bidir.UpdateCommentPolicy
instance GHC.Classes.Eq Data.Ini.Config.Bidir.UpdatePolicy
instance GHC.Internal.Base.Functor (Data.Ini.Config.Bidir.C a)
instance GHC.Internal.Base.Functor Data.Ini.Config.Bidir.I
instance GHC.Internal.Base.Functor (Data.Ini.Config.Bidir.IniSpec s)
instance GHC.Internal.Base.Functor (Data.Ini.Config.Bidir.SectionSpec s)
instance GHC.Internal.Base.Monad (Data.Ini.Config.Bidir.IniSpec s)
instance GHC.Internal.Base.Monad (Data.Ini.Config.Bidir.SectionSpec s)
instance GHC.Internal.Show.Show Data.Ini.Config.Bidir.UpdateCommentPolicy
instance GHC.Internal.Show.Show Data.Ini.Config.Bidir.UpdatePolicy


-- | The 'config-ini' library exports some simple monadic functions to make
--   parsing INI-like configuration easier. INI files have a two-level
--   structure: the top-level named chunks of configuration, and the
--   individual key-value pairs contained within those chunks. For example,
--   the following INI file has two sections, <tt>NETWORK</tt> and
--   <tt>LOCAL</tt>, and each contains its own key-value pairs. Comments,
--   which begin with <tt>#</tt> or <tt>;</tt>, are ignored:
--   
--   <pre>
--   [NETWORK]
--   host = example.com
--   port = 7878
--   
--   # here is a comment
--   [LOCAL]
--   user = terry
--   </pre>
--   
--   The combinators provided here are designed to write quick and
--   idiomatic parsers for files of this form. Sections are parsed by
--   <a>IniParser</a> computations, like <a>section</a> and its variations,
--   while the fields within sections are parsed by <a>SectionParser</a>
--   computations, like <a>field</a> and its variations. If we want to
--   parse an INI file like the one above, treating the entire
--   <tt>LOCAL</tt> section as optional, we can write it like this:
--   
--   <pre>
--   data Config = Config
--     { cfNetwork :: NetworkConfig, cfLocal :: Maybe LocalConfig }
--       deriving (Eq, Show)
--   
--   data NetworkConfig = NetworkConfig
--     { netHost :: String, netPort :: Int }
--       deriving (Eq, Show)
--   
--   data LocalConfig = LocalConfig
--     { localUser :: Text }
--       deriving (Eq, Show)
--   
--   configParser :: IniParser Config
--   configParser = do
--     netCf &lt;- section "NETWORK" $ do
--       host &lt;- fieldOf "host" string
--       port &lt;- fieldOf "port" number
--       return NetworkConfig { netHost = host, netPort = port }
--     locCf &lt;- sectionMb "LOCAL" $
--       LocalConfig &lt;$&gt; field "user"
--     return Config { cfNetwork = netCf, cfLocal = locCf }
--   </pre>
--   
--   We can run our computation with <a>parseIniFile</a>, which, when run
--   on our example file above, would produce the following:
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile example configParser
--   Right (Config {cfNetwork = NetworkConfig {netHost = "example.com", netPort = 7878}, cfLocal = Just (LocalConfig {localUser = "terry"})})
--   </pre>
module Data.Ini.Config

-- | Parse a <a>Text</a> value as an INI file and run an <a>IniParser</a>
--   over it
parseIniFile :: Text -> IniParser a -> Either String a

-- | An <a>IniParser</a> value represents a computation for parsing entire
--   INI-format files.
data IniParser a

-- | A <a>SectionParser</a> value represents a computation for parsing a
--   single section of an INI-format file.
data SectionParser a

-- | Find a named section in the INI file and parse it with the provided
--   section parser, failing if the section does not exist. In order to
--   support classic INI files with capitalized section names, section
--   lookup is <b>case-insensitive</b>.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n" $ section "ONE" (field "x")
--   Right "hello"
--   
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n" $ section "TWO" (field "x")
--   Left "No top-level section named \"TWO\""
--   </pre>
section :: Text -> SectionParser a -> IniParser a

-- | Find multiple named sections in the INI file and parse them all with
--   the provided section parser. In order to support classic INI files
--   with capitalized section names, section lookup is
--   <b>case-insensitive</b>.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n[ONE]\nx = goodbye\n" $ sections "ONE" (field "x")
--   Right (fromList ["hello","goodbye"])
--   
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n" $ sections "TWO" (field "x")
--   Right (fromList [])
--   </pre>
sections :: Text -> SectionParser a -> IniParser (Seq a)

-- | A call to <tt>sectionOf f</tt> will apply <tt>f</tt> to each section
--   name and, if <tt>f</tt> produces a <a>Just</a> value, pass the
--   extracted value in order to get the <a>SectionParser</a> to use for
--   that section. This will find at most one section, and will produce an
--   error if no section exists.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[FOO]\nx = hello\n" $ sectionOf (T.stripSuffix "OO") (\ l -&gt; fmap ((,) l) (field "x"))
--   Right ("F","hello")
--   
--   &gt;&gt;&gt; parseIniFile "[BAR]\nx = hello\n" $ sectionOf (T.stripSuffix "OO") (\ l -&gt; fmap ((,) l) (field "x"))
--   Left "No matching top-level section"
--   </pre>
sectionOf :: (Text -> Maybe b) -> (b -> SectionParser a) -> IniParser a

-- | A call to <tt>sectionsOf f</tt> will apply <tt>f</tt> to each section
--   name and, if <tt>f</tt> produces a <tt>Just</tt> value, pass the
--   extracted value in order to get the <a>SectionParser</a> to use for
--   that section. This will return every section for which the call to
--   <tt>f</tt> produces a <a>Just</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[FOO]\nx = hello\n[BOO]\nx = goodbye\n" $ sectionsOf (T.stripSuffix "OO") (\ l -&gt; fmap ((,) l) (field "x"))
--   Right (fromList [("F","hello"),("B","goodbye")])
--   
--   &gt;&gt;&gt; parseIniFile "[BAR]\nx = hello\n" $ sectionsOf (T.stripSuffix "OO") (\ l -&gt; fmap ((,) l) (field "x"))
--   Right (fromList [])
--   </pre>
sectionsOf :: (Text -> Maybe b) -> (b -> SectionParser a) -> IniParser (Seq a)

-- | Find a named section in the INI file and parse it with the provided
--   section parser, returning <a>Nothing</a> if the section does not
--   exist. In order to support classic INI files with capitalized section
--   names, section lookup is <b>case-insensitive</b>.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n" $ sectionMb "ONE" (field "x")
--   Right (Just "hello")
--   
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n" $ sectionMb "TWO" (field "x")
--   Right Nothing
--   </pre>
sectionMb :: Text -> SectionParser a -> IniParser (Maybe a)

-- | Find a named section in the INI file and parse it with the provided
--   section parser, returning a default value if the section does not
--   exist. In order to support classic INI files with capitalized section
--   names, section lookup is <b>case-insensitive</b>.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n" $ sectionDef "ONE" "def" (field "x")
--   Right "hello"
--   
--   &gt;&gt;&gt; parseIniFile "[ONE]\nx = hello\n" $ sectionDef "TWO" "def" (field "x")
--   Right "def"
--   </pre>
sectionDef :: Text -> a -> SectionParser a -> IniParser a

-- | Retrieve a field, failing if it doesn't exist, and return its raw
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (field "x")
--   Right "hello"
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (field "y")
--   Left "Missing field \"y\" in section \"MAIN\""
--   </pre>
field :: Text -> SectionParser Text

-- | Retrieve a field and use the supplied parser to parse it as a value,
--   failing if the field does not exist, or if the parser fails to produce
--   a value.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = 72\n" $ section "MAIN" (fieldOf "x" number)
--   Right 72
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldOf "x" number)
--   Left "Line 2, in section \"MAIN\": Unable to parse \"hello\" as a value of type Integer"
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = 72\n" $ section "MAIN" (fieldOf "y" number)
--   Left "Missing field \"y\" in section \"MAIN\""
--   </pre>
fieldOf :: Text -> (Text -> Either String a) -> SectionParser a

-- | Retrieve a field, returning a <tt>Nothing</tt> value if it does not
--   exist.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldMb "x")
--   Right (Just "hello")
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldMb "y")
--   Right Nothing
--   </pre>
fieldMb :: Text -> SectionParser (Maybe Text)

-- | Retrieve a field and parse it according to the given parser, returning
--   <tt>Nothing</tt> if it does not exist. If the parser fails, then this
--   will fail.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = 72\n" $ section "MAIN" (fieldMbOf "x" number)
--   Right (Just 72)
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldMbOf "x" number)
--   Left "Line 2, in section \"MAIN\": Unable to parse \"hello\" as a value of type Integer"
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = 72\n" $ section "MAIN" (fieldMbOf "y" number)
--   Right Nothing
--   </pre>
fieldMbOf :: Text -> (Text -> Either String a) -> SectionParser (Maybe a)

-- | Retrieve a field and supply a default value for if it doesn't exist.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldDef "x" "def")
--   Right "hello"
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldDef "y" "def")
--   Right "def"
--   </pre>
fieldDef :: Text -> Text -> SectionParser Text

-- | Retrieve a field, parsing it according to the given parser, and
--   returning a default value if it does not exist. If the parser fails,
--   then this will fail.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = 72\n" $ section "MAIN" (fieldDefOf "x" number 99)
--   Right 72
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldDefOf "x" number 99)
--   Left "Line 2, in section \"MAIN\": Unable to parse \"hello\" as a value of type Integer"
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = 72\n" $ section "MAIN" (fieldDefOf "y" number 99)
--   Right 99
--   </pre>
fieldDefOf :: Text -> (Text -> Either String a) -> a -> SectionParser a

-- | Retrieve a field and treat it as a boolean, failing if it does not
--   exist.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = yes\n" $ section "MAIN" (fieldFlag "x")
--   Right True
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = yes\n" $ section "MAIN" (fieldFlag "y")
--   Left "Missing field \"y\" in section \"MAIN\""
--   </pre>
fieldFlag :: Text -> SectionParser Bool

-- | Retrieve a field and treat it as a boolean, subsituting a default
--   value if it doesn't exist.
--   
--   <pre>
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = yes\n" $ section "MAIN" (fieldFlagDef "x" False)
--   Right True
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = hello\n" $ section "MAIN" (fieldFlagDef "x" False)
--   Left "Line 2, in section \"MAIN\": Unable to parse \"hello\" as a boolean"
--   
--   &gt;&gt;&gt; parseIniFile "[MAIN]\nx = yes\n" $ section "MAIN" (fieldFlagDef "y" False)
--   Right False
--   </pre>
fieldFlagDef :: Text -> Bool -> SectionParser Bool

-- | Try to use the <a>Read</a> instance for a type to parse a value,
--   failing with a human-readable error message if reading fails.
--   
--   <pre>
--   &gt;&gt;&gt; readable "(5, 7)" :: Either String (Int, Int)
--   Right (5,7)
--   
--   &gt;&gt;&gt; readable "hello" :: Either String (Int, Int)
--   Left "Unable to parse \"hello\" as a value of type (Int,Int)"
--   </pre>
readable :: (Read a, Typeable a) => Text -> Either String a

-- | Try to use the <a>Read</a> instance for a numeric type to parse a
--   value, failing with a human-readable error message if reading fails.
--   
--   <pre>
--   &gt;&gt;&gt; number "5" :: Either String Int
--   Right 5
--   
--   &gt;&gt;&gt; number "hello" :: Either String Int
--   Left "Unable to parse \"hello\" as a value of type Int"
--   </pre>
number :: (Num a, Read a, Typeable a) => Text -> Either String a

-- | Convert a textual value to the appropriate string type. This will
--   never fail.
--   
--   <pre>
--   &gt;&gt;&gt; string "foo" :: Either String String
--   Right "foo"
--   </pre>
string :: IsString a => Text -> Either String a

-- | Convert a string that represents a boolean to a proper boolean. This
--   is case-insensitive, and matches the words <tt>true</tt>,
--   <tt>false</tt>, <tt>yes</tt>, <tt>no</tt>, as well as single-letter
--   abbreviations for all of the above. If the input does not match, then
--   this will fail with a human-readable error message.
--   
--   <pre>
--   &gt;&gt;&gt; flag "TRUE"
--   Right True
--   
--   &gt;&gt;&gt; flag "y"
--   Right True
--   
--   &gt;&gt;&gt; flag "no"
--   Right False
--   
--   &gt;&gt;&gt; flag "F"
--   Right False
--   
--   &gt;&gt;&gt; flag "That's a secret!"
--   Left "Unable to parse \"That's a secret!\" as a boolean"
--   </pre>
flag :: Text -> Either String Bool

-- | Convert a reader for a value into a reader for a list of those values,
--   separated by a chosen separator. This will split apart the string on
--   that separator, get rid of leading and trailing whitespace on the
--   individual chunks, and then attempt to parse each of them according to
--   the function provided, turning the result into a list.
--   
--   This is overloaded with the <a>IsList</a> typeclass, so it can be used
--   transparently to parse other list-like types.
--   
--   <pre>
--   &gt;&gt;&gt; listWithSeparator "," number "2, 3, 4" :: Either String [Int]
--   Right [2,3,4]
--   
--   &gt;&gt;&gt; listWithSeparator " " number "7 8 9" :: Either String [Int]
--   Right [7,8,9]
--   
--   &gt;&gt;&gt; listWithSeparator ":" string "/bin:/usr/bin" :: Either String [FilePath]
--   Right ["/bin","/usr/bin"]
--   
--   &gt;&gt;&gt; listWithSeparator "," number "7 8 9" :: Either String [Int]
--   Left "Unable to parse \"7 8 9\" as a value of type Int"
--   </pre>
listWithSeparator :: IsList l => Text -> (Text -> Either String (Item l)) -> Text -> Either String l
instance GHC.Internal.Base.Alternative Data.Ini.Config.IniParser
instance GHC.Internal.Base.Alternative Data.Ini.Config.SectionParser
instance GHC.Internal.Base.Applicative Data.Ini.Config.IniParser
instance GHC.Internal.Base.Applicative Data.Ini.Config.SectionParser
instance GHC.Internal.Base.Functor Data.Ini.Config.IniParser
instance GHC.Internal.Base.Functor Data.Ini.Config.SectionParser
instance GHC.Internal.Base.Monad Data.Ini.Config.IniParser
instance GHC.Internal.Base.Monad Data.Ini.Config.SectionParser
