-- 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.1.4 -- | Internal types for Data.ConfigFile. This module is not intended -- to be used directly by your programs. -- -- Copyright (c) 2004-2008 John Goerzen, jgoerzen@complete.org -- -- This program is distributed in the hope that it will be useful, but -- WITHOUT ANY WARRANTY; without even the implied warranty of -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 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 ConfigFile. 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 interpolatingAccess 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 ConfigFile. 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 -- usedefault 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 GHC.Show.Show Data.ConfigFile.Types.CPErrorData instance GHC.Classes.Ord Data.ConfigFile.Types.CPErrorData instance GHC.Classes.Eq Data.ConfigFile.Types.CPErrorData instance Control.Monad.Trans.Error.Error Data.ConfigFile.Types.CPError -- | Parser support for Data.ConfigFile. This module is not intended -- to be used directly by your programs. -- -- Copyright (c) 2004-2008 John Goerzen, jgoerzen@complete.org -- -- This program is distributed in the hope that it will be useful, but -- WITHOUT ANY WARRANTY; without even the implied warranty of -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 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 program is distributed in the hope that it will be useful, but -- WITHOUT ANY WARRANTY; without even the implied warranty of -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -- -- 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 ConfigFile. 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 -- usedefault 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 interpolatingAccess 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 ConfigFile object. -- -- The content contains only an empty mandatory DEFAULT section. -- -- optionxform is set to map toLower. -- -- usedefault is set to True. -- -- accessfunc is set to simpleAccess. 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 -- Text.Printf, 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 get and friends to return a new -- CPError: InterpolationError. This error would be -- returned when: -- -- -- -- 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 usedefault is True, in -- DEFAULT according to the normal logic. -- -- To use a literal percent sign, you must place %% in the -- configuration file when interpolation is used. -- -- Here is how you might enable interpolation: -- -- 
--   let cp2 = cp {accessfunc = interpolatingAccess 10}
--
-- -- The cp2 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 -- ConfigParser using the semantics documented under merge -- with the new data taking precedence over the old. However, unlike -- merge, 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 readfile, but uses an already-open handle. You should use -- readfile 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 readfile, but uses a string. You should use -- readfile 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 "get". class Get_C a -- | Retrieves a string from the configuration file. -- -- When used in a context where a String is expected, returns that string -- verbatim. -- -- When used in a context where a Bool is expected, parses the string to -- a Boolean value (see logic below). -- -- When used in a context where anything that is an instance of Read is -- expected, calls read to parse the item. -- -- An error will be returned of no such option could be found or if it -- could not be parsed as a boolean (when returning a Bool). -- -- When parsing to a Bool, strings are case-insentively converted as -- follows: -- -- The following will produce a True value: -- -- -- -- The following will produce a False value: -- -- 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 DEFAULT. sections :: ConfigParser -> [SectionSpec] -- | Indicates whether the given section exists. -- -- No special DEFAULT 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 DEFAULT processing is done. No exception -- could be raised or error returned. has_option :: ConfigParser -> SectionSpec -> OptionSpec -> Bool -- | Returns a list of (optionname, value) 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 NoSection error if the -- section does not exist and a NoOption error if the option does -- not exist. Otherwise, returns the new ConfigParser object. remove_option :: MonadError CPError m => ConfigParser -> SectionSpec -> OptionSpec -> m ConfigParser -- | Adds the specified section name. Returns a SectionAlreadyExists -- error if the section was already present. Otherwise, returns the new -- ConfigParser object. add_section :: MonadError CPError m => ConfigParser -> SectionSpec -> m ConfigParser -- | Removes the specified section. Returns a NoSection error if the -- section does not exist; otherwise, returns the new ConfigParser -- object. -- -- This call may not be used to remove the DEFAULT section. -- Attempting to do so will always cause a NoSection error. remove_section :: MonadError CPError m => ConfigParser -> SectionSpec -> m ConfigParser -- | Combines two ConfigParsers into one. -- -- Any duplicate options are resolved to contain the value specified in -- the second parser. -- -- The ConfigParser 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 ConfigParser 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 Data.ConfigFile.Get_C GHC.Base.String instance Data.ConfigFile.Get_C GHC.Types.Bool instance GHC.Read.Read t => Data.ConfigFile.Get_C t module Data.ConfigFile.Monadic simpleAccess :: MonadError CPError m => SectionSpec -> OptionSpec -> ConfigParser -> m String interpolatingAccess :: MonadError CPError m => Int -> SectionSpec -> OptionSpec -> ConfigParser -> m String readfile :: MonadError CPError m => FilePath -> ConfigParser -> IO (m ConfigParser) readhandle :: MonadError CPError m => Handle -> ConfigParser -> IO (m ConfigParser) readstring :: MonadError CPError m => String -> ConfigParser -> m ConfigParser has_section :: SectionSpec -> ConfigParser -> Bool options :: MonadError CPError m => SectionSpec -> ConfigParser -> m [OptionSpec] has_option :: SectionSpec -> OptionSpec -> ConfigParser -> Bool items :: MonadError CPError m => SectionSpec -> ConfigParser -> m [(OptionSpec, String)] set :: MonadError CPError m => SectionSpec -> OptionSpec -> String -> ConfigParser -> m ConfigParser setshow :: (Show a, MonadError CPError m) => SectionSpec -> OptionSpec -> a -> ConfigParser -> m ConfigParser remove_option :: MonadError CPError m => SectionSpec -> OptionSpec -> ConfigParser -> m ConfigParser add_section :: MonadError CPError m => SectionSpec -> ConfigParser -> m ConfigParser remove_section :: MonadError CPError m => SectionSpec -> ConfigParser -> m ConfigParser