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


-- | Configuration file reading & writing
--   
--   Parser and writer for handling sectioned config files in Haskell.
--   
--   The ConfigFile module works with configuration files in a standard
--   format that is easy for the user to edit, easy for the programmer to
--   work with, yet remains powerful and flexible. It is inspired by, and
--   compatible with, Python's ConfigParser module. It uses files that
--   resemble Windows .INI-style files, but with numerous improvements.
--   
--   ConfigFile provides simple calls to both read and write config files.
--   It's possible to make a config file parsable by this module, the Unix
--   shell, and make.
@package ConfigFile
@version 1.0.4


-- | Internal types for <a>Data.ConfigFile</a>. This module is not intended
--   to be used directly by your programs.
--   
--   Copyright (c) 2004-2008 John Goerzen, jgoerzen@complete.org
module Data.ConfigFile.Types

-- | Storage of options.
type CPOptions = Map OptionSpec String

-- | The main data storage type (storage of sections).
--   
--   PLEASE NOTE: This type is exported only for use by other modules under
--   Data.ConfigFile. You should NEVER access the FiniteMap in a
--   ConfigParser directly. This type may change in future releases of
--   MissingH, which could break your programs. Please retrict yourself to
--   the interface in <tt>Data.ConfigFile</tt>.
type CPData = Map SectionSpec CPOptions

-- | Possible ConfigParser errors.
data CPErrorData

-- | Parse error
ParseError :: String -> CPErrorData

-- | Attempt to create an already-existing ection
SectionAlreadyExists :: SectionSpec -> CPErrorData

-- | The section does not exist
NoSection :: SectionSpec -> CPErrorData

-- | The option does not exist
NoOption :: OptionSpec -> CPErrorData

-- | Miscellaneous error
OtherProblem :: String -> CPErrorData

-- | Raised by <tt>Data.ConfigFile.interpolatingAccess</tt> if a request
--   was made for a non-existant option
InterpolationError :: String -> CPErrorData

-- | Indicates an error occurred. The String is an explanation of the
--   location of the error.
type CPError = (CPErrorData, String)

-- | This is the main record that is used by <tt>Data.ConfigFile</tt>.
data ConfigParser
ConfigParser :: CPData -> (OptionSpec -> OptionSpec) -> (ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String) -> Bool -> (ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String) -> ConfigParser

-- | The data itself
content :: ConfigParser -> CPData

-- | How to transform an option into a standard representation
optionxform :: ConfigParser -> (OptionSpec -> OptionSpec)

-- | Function to look up an option, considering a default value if
--   <a>usedefault</a> is True; or ignoring a default value otherwise. The
--   option specification is assumed to be already transformed.
defaulthandler :: ConfigParser -> ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String

-- | Whether or not to seek out a default action when no match is found.
usedefault :: ConfigParser -> Bool

-- | Function that is used to perform lookups, do optional interpolation,
--   etc. It is assumed that accessfunc will internally call defaulthandler
--   to do the underlying lookup. The option value is not assumed to be
--   transformed.
accessfunc :: ConfigParser -> (ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String)

-- | Names of sections
type SectionSpec = String

-- | Names of options
type OptionSpec = String

-- | Internal output from parser
type ParseOutput = [(String, [(String, String)])]
instance [overlap ok] Eq CPErrorData
instance [overlap ok] Ord CPErrorData
instance [overlap ok] Show CPErrorData
instance [overlap ok] Error CPError


-- | Parser support for <a>Data.ConfigFile</a>. This module is not intended
--   to be used directly by your programs.
--   
--   Copyright (c) 2004-2008 John Goerzen, jgoerzen@complete.org
module Data.ConfigFile.Parser
parse_string :: (MonadError CPError m) => String -> m ParseOutput
parse_file :: (MonadError CPError m) => FilePath -> IO (m ParseOutput)
parse_handle :: (MonadError CPError m) => Handle -> IO (m ParseOutput)
interpmain :: (String -> Either CPError String) -> Parser String

-- | Internal output from parser
type ParseOutput = [(String, [(String, String)])]


-- | Configuration file parsing, generation, and manipulation
--   
--   Copyright (c) 2004-2008 John Goerzen, jgoerzen@complete.org
--   
--   This module contains extensive documentation. Please scroll down to
--   the Introduction section to continue reading.
module Data.ConfigFile

-- | Names of sections
type SectionSpec = String

-- | Names of options
type OptionSpec = String

-- | This is the main record that is used by <tt>Data.ConfigFile</tt>.
data ConfigParser
ConfigParser :: CPData -> (OptionSpec -> OptionSpec) -> (ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String) -> Bool -> (ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String) -> ConfigParser

-- | The data itself
content :: ConfigParser -> CPData

-- | How to transform an option into a standard representation
optionxform :: ConfigParser -> (OptionSpec -> OptionSpec)

-- | Function to look up an option, considering a default value if
--   <a>usedefault</a> is True; or ignoring a default value otherwise. The
--   option specification is assumed to be already transformed.
defaulthandler :: ConfigParser -> ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String

-- | Whether or not to seek out a default action when no match is found.
usedefault :: ConfigParser -> Bool

-- | Function that is used to perform lookups, do optional interpolation,
--   etc. It is assumed that accessfunc will internally call defaulthandler
--   to do the underlying lookup. The option value is not assumed to be
--   transformed.
accessfunc :: ConfigParser -> (ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String)

-- | Possible ConfigParser errors.
data CPErrorData

-- | Parse error
ParseError :: String -> CPErrorData

-- | Attempt to create an already-existing ection
SectionAlreadyExists :: SectionSpec -> CPErrorData

-- | The section does not exist
NoSection :: SectionSpec -> CPErrorData

-- | The option does not exist
NoOption :: OptionSpec -> CPErrorData

-- | Miscellaneous error
OtherProblem :: String -> CPErrorData

-- | Raised by <tt>Data.ConfigFile.interpolatingAccess</tt> if a request
--   was made for a non-existant option
InterpolationError :: String -> CPErrorData

-- | Indicates an error occurred. The String is an explanation of the
--   location of the error.
type CPError = (CPErrorData, String)

-- | The default empty <tt>Data.ConfigFile</tt> object.
--   
--   The content contains only an empty mandatory <tt>DEFAULT</tt> section.
--   
--   <a>optionxform</a> is set to <tt>map toLower</tt>.
--   
--   <a>usedefault</a> is set to <tt>True</tt>.
--   
--   <a>accessfunc</a> is set to <a>simpleAccess</a>.
emptyCP :: ConfigParser

-- | Default (non-interpolating) access function
simpleAccess :: (MonadError CPError m) => ConfigParser -> SectionSpec -> OptionSpec -> m String

-- | Interpolating access function. Please see the Interpolation section
--   above for a background on interpolation.
--   
--   Although the format string looks similar to one used by
--   <a>Text.Printf</a>, it is not the same. In particular, only the
--   %(...)s format is supported. No width specifiers are supported and no
--   conversions other than s are supported.
--   
--   To use this function, you must specify a maximum recursion depth for
--   interpolation. This is used to prevent a stack overflow in the event
--   that the configuration file contains an endless interpolation loop.
--   Values of 10 or so are usually more than enough, though you could
--   probably go into the hundreds or thousands before you have actual
--   problems.
--   
--   A value less than one will cause an instant error every time you
--   attempt a lookup.
--   
--   This access method can cause <a>get</a> and friends to return a new
--   <a>CPError</a>: <a>InterpolationError</a>. This error would be
--   returned when:
--   
--   <ul>
--   <li>The configuration file makes a reference to an option that does
--   not exist</li>
--   <li>The maximum interpolation depth is exceeded</li>
--   <li>There is a syntax error processing a %-directive in the
--   configuration file</li>
--   </ul>
--   
--   An interpolation lookup name specifies an option only. There is no
--   provision to specify a section. Interpolation variables are looked up
--   in the current section, and, if <a>usedefault</a> is True, in
--   <tt>DEFAULT</tt> according to the normal logic.
--   
--   To use a literal percent sign, you must place <tt>%%</tt> in the
--   configuration file when interpolation is used.
--   
--   Here is how you might enable interpolation:
--   
--   <pre>
--   let cp2 = cp {accessfunc = interpolatingAccess 10}
--   </pre>
--   
--   The <tt>cp2</tt> object will now support interpolation with a maximum
--   depth of 10.
interpolatingAccess :: (MonadError CPError m) => Int -> ConfigParser -> SectionSpec -> OptionSpec -> m String

-- | Loads data from the specified file. It is then combined with the given
--   <a>ConfigParser</a> using the semantics documented under <a>merge</a>
--   with the new data taking precedence over the old. However, unlike
--   <a>merge</a>, all the options as set in the old object are preserved
--   since the on-disk representation does not convey those options.
--   
--   May return an error if there is a syntax error. May raise an exception
--   if the file could not be accessed.
readfile :: (MonadError CPError m) => ConfigParser -> FilePath -> IO (m ConfigParser)

-- | Like <a>readfile</a>, but uses an already-open handle. You should use
--   <a>readfile</a> instead of this if possible, since it will be able to
--   generate better error messages.
--   
--   Errors would be returned on a syntax error.
readhandle :: (MonadError CPError m) => ConfigParser -> Handle -> IO (m ConfigParser)

-- | Like <a>readfile</a>, but uses a string. You should use
--   <a>readfile</a> instead of this if you are processing a file, since it
--   can generate better error messages.
--   
--   Errors would be returned on a syntax error.
readstring :: (MonadError CPError m) => ConfigParser -> String -> m ConfigParser

-- | The class representing the data types that can be returned by
--   <a>get</a>.
class Get_C a
get :: (Get_C a, MonadError CPError m) => ConfigParser -> SectionSpec -> OptionSpec -> m a

-- | Returns a list of sections in your configuration file. Never includes
--   the always-present section <tt>DEFAULT</tt>.
sections :: ConfigParser -> [SectionSpec]

-- | Indicates whether the given section exists.
--   
--   No special <tt>DEFAULT</tt> processing is done.
has_section :: ConfigParser -> SectionSpec -> Bool

-- | Returns a list of the names of all the options present in the given
--   section.
--   
--   Returns an error if the given section does not exist.
options :: (MonadError CPError m) => ConfigParser -> SectionSpec -> m [OptionSpec]

-- | Indicates whether the given option is present. Returns True only if
--   the given section is present AND the given option is present in that
--   section. No special <tt>DEFAULT</tt> processing is done. No exception
--   could be raised or error returned.
has_option :: ConfigParser -> SectionSpec -> OptionSpec -> Bool

-- | Returns a list of <tt>(optionname, value)</tt> pairs representing the
--   content of the given section. Returns an error the section is invalid.
items :: (MonadError CPError m) => ConfigParser -> SectionSpec -> m [(OptionSpec, String)]

-- | Sets the option to a new value, replacing an existing one if it
--   exists.
--   
--   Returns an error if the section does not exist.
set :: (MonadError CPError m) => ConfigParser -> SectionSpec -> OptionSpec -> String -> m ConfigParser

-- | Sets the option to a new value, replacing an existing one if it
--   exists. It requires only a showable value as its parameter. This can
--   be used with bool values, as well as numeric ones.
--   
--   Returns an error if the section does not exist.
setshow :: (Show a, MonadError CPError m) => ConfigParser -> SectionSpec -> OptionSpec -> a -> m ConfigParser

-- | Removes the specified option. Returns a <a>NoSection</a> error if the
--   section does not exist and a <a>NoOption</a> error if the option does
--   not exist. Otherwise, returns the new <a>ConfigParser</a> object.
remove_option :: (MonadError CPError m) => ConfigParser -> SectionSpec -> OptionSpec -> m ConfigParser

-- | Adds the specified section name. Returns a <a>SectionAlreadyExists</a>
--   error if the section was already present. Otherwise, returns the new
--   <a>ConfigParser</a> object.
add_section :: (MonadError CPError m) => ConfigParser -> SectionSpec -> m ConfigParser

-- | Removes the specified section. Returns a <a>NoSection</a> error if the
--   section does not exist; otherwise, returns the new <a>ConfigParser</a>
--   object.
--   
--   This call may not be used to remove the <tt>DEFAULT</tt> section.
--   Attempting to do so will always cause a <a>NoSection</a> error.
remove_section :: (MonadError CPError m) => ConfigParser -> SectionSpec -> m ConfigParser

-- | Combines two <a>ConfigParser</a>s into one.
--   
--   Any duplicate options are resolved to contain the value specified in
--   the second parser.
--   
--   The <a>ConfigParser</a> options in the resulting object will be set as
--   they are in the second one passed to this function.
merge :: ConfigParser -> ConfigParser -> ConfigParser

-- | Converts the <a>ConfigParser</a> to a string representation that could
--   be later re-parsed by this module or modified by a human.
--   
--   Note that this does not necessarily re-create a file that was
--   originally loaded. Things may occur in a different order, comments
--   will be removed, etc. The conversion makes an effort to make the
--   result human-editable, but it does not make an effort to make the
--   result identical to the original input.
--   
--   The result is, however, guaranteed to parse the same as the original
--   input.
to_string :: ConfigParser -> String
instance [overlap ok] (Num t, Read t) => Get_C t
instance [overlap ok] Get_C Bool
instance [overlap ok] Get_C String