1{-
2Copyright (C) 2004-2008 John Goerzen <jgoerzen@complete.org>
3
4This program is free software; you can redistribute it and/or modify it, as
5specified in the COPYRIGHT file, under the terms of either version 2.1 of
6the LGPL (or, at your option, any later version) or the 3-clause BSD license.
7-}
8
9{- |
10   Module     : Data.ConfigFile.Types
11   Copyright  : Copyright (C) 2004-2008 John Goerzen
12   License    : Either LGPL or BSD3, as specified in the COPYRIGHT file.
13
14   Maintainer : John Goerzen <jgoerzen@complete.org>
15   Stability  : provisional
16   Portability: portable
17
18Internal types for "Data.ConfigFile".  This module is not intended to be
19used directly by your programs.
20
21Copyright (c) 2004-2008 John Goerzen, jgoerzen\@complete.org
22
23This program is distributed in the hope that it will be useful,
24but WITHOUT ANY WARRANTY; without even the implied warranty of
25MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
26
27-}
28
29module Data.ConfigFile.Types (
30                                    CPOptions, CPData,
31                                    CPErrorData(..), CPError, {-CPResult,-}
32                                    ConfigParser(..),
33                                    SectionSpec,
34                                    OptionSpec,
35                                    ParseOutput
36                                   ) where
37import qualified Data.Map as Map
38import Data.Char
39import Control.Monad.Error
40
41{- | Internal output from parser -}
42type ParseOutput = [(String, [(String, String)])]
43
44{- | Names of sections -}
45type SectionSpec = String
46
47{- | Names of options -}
48type OptionSpec = String
49
50{- | Storage of options. -}
51type CPOptions = Map.Map OptionSpec String
52
53{- | The main data storage type (storage of sections).
54
55PLEASE NOTE: This type is exported only for use by other modules under
56Data.ConfigFile.  You should NEVER access the FiniteMap in a ConfigParser
57directly.  This type may change in future releases of MissingH, which could
58break your programs.  Please retrict yourself to the interface in
59'Data.ConfigFile'.
60 -}
61type CPData = Map.Map SectionSpec CPOptions
62
63{- | Possible ConfigParser errors. -}
64data CPErrorData = ParseError String        -- ^ Parse error
65                 | SectionAlreadyExists SectionSpec -- ^ Attempt to create an already-existing ection
66                 | NoSection SectionSpec    -- ^ The section does not exist
67                 | NoOption OptionSpec      -- ^ The option does not exist
68                 | OtherProblem String      -- ^ Miscellaneous error
69                 | InterpolationError String -- ^ Raised by 'Data.ConfigFile.interpolatingAccess' if a request was made for a non-existant option
70                   deriving (Eq, Ord, Show)
71
72{- | Indicates an error occurred.  The String is an explanation of the location
73of the error. -}
74type CPError = (CPErrorData, String)
75
76instance Error CPError where
77    noMsg = (OtherProblem "", "")
78    strMsg x = (OtherProblem x, "")
79
80{- Removed due to Hugs incompatibility.
81
82| Basic ConfigParser error handling.  The Left value indicates
83an error, while a Right value indicates success.
84type CPResult a = MonadError CPError m => m a
85-}
86
87{- | This is the main record that is used by 'Data.ConfigFile'.
88-}
89data ConfigParser = ConfigParser
90    { -- | The data itself
91      content :: CPData,
92      -- | How to transform an option into a standard representation
93      optionxform :: (OptionSpec -> OptionSpec),
94      -- | Function to look up an option, considering a default value
95      -- if 'usedefault' is True; or ignoring a default value otherwise.
96      -- The option specification is assumed to be already transformed.
97      defaulthandler :: ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String,
98      -- | Whether or not to seek out a default action when no match
99      -- is found.
100      usedefault :: Bool,
101      -- | Function that is used to perform lookups, do optional
102      -- interpolation, etc.  It is assumed that accessfunc
103      -- will internally call defaulthandler to do the underlying lookup.
104      -- The option value is not assumed to be transformed.
105      accessfunc :: (ConfigParser -> SectionSpec -> OptionSpec -> Either CPError String)
106    }
107