Documentation for raw types
Getty Ritter
7 years ago
| 1 | 1 | module Data.Ini.Config.Raw |
| 2 |
( |
|
| 2 | ( -- $main | |
| 3 | -- * INI types | |
| 4 | Ini(..) | |
| 3 | 5 | , IniSection(..) |
| 4 | 6 | , IniValue(..) |
| 5 | 7 | , BlankLine(..) |
| 8 | -- * serializing and deserializing | |
| 6 | 9 | , parseIni |
| 7 | 10 | , printIni |
| 8 | 11 | ) where |
| 20 | 23 | import Text.Megaparsec.Text |
| 21 | 24 | |
| 22 | 25 | -- | An 'Ini' value is a mapping from section names to |
| 23 |
-- 'IniSection' values. |
|
| 26 | -- 'IniSection' values. The section names in this mapping are | |
| 27 | -- normalized to lower-case and stripped of whitespace. This | |
| 28 | -- sequence retains the ordering of the original source file. | |
| 24 | 29 | newtype Ini = Ini |
| 25 | 30 | { fromIni :: Seq (Text, IniSection) |
| 26 | 31 | } deriving (Eq, Show) |
| 27 | 32 | |
| 28 | 33 | -- | An 'IniSection' consists of a name, a mapping of key-value pairs, |
| 29 |
-- and metadata about where the section starts and ends in the |
|
| 34 | -- and metadata about where the section starts and ends in the | |
| 35 | -- file. The section names found in 'isName' are *not* normalized to | |
| 36 | -- lower-case or stripped of whitespace, and thus should appear | |
| 37 | -- exactly as they appear in the original source file. | |
| 30 | 38 | data IniSection = IniSection |
| 31 | 39 | { isName :: Text |
| 40 | -- ^ The name of the section, as it appears in the | |
| 41 | -- original INI source | |
| 32 | 42 | , isVals :: Seq (Text, IniValue) |
| 43 | -- ^ The key-value mapping within that section. Key | |
| 44 | -- names here are normalized to lower-case and | |
| 45 | -- stripped of whitespace. This sequence retains | |
| 46 | -- the ordering of the original source file. | |
| 33 | 47 | , isStartLine :: Int |
| 48 | -- ^ The line on which the section begins. This | |
| 49 | -- field is ignored when serializing, and is only | |
| 50 | -- used for error messages produced when parsing | |
| 51 | -- and deserializing an INI structure. | |
| 34 | 52 | , isEndLine :: Int |
| 53 | -- ^ The line on which the section ends. This field | |
| 54 | -- is ignored when serializing, and is only used | |
| 55 | -- for error messages produced when parsing and | |
| 56 | -- deserializing an INI structure. | |
| 35 | 57 | , isComments :: Seq BlankLine |
| 58 | -- ^ The blank lines and comments that appear prior | |
| 59 | -- to the section head declaration, retained for | |
| 60 | -- pretty-printing identical INI files. | |
| 36 | 61 | } deriving (Eq, Show) |
| 37 | 62 | |
| 38 | 63 | -- | An 'IniValue' represents a key-value mapping, and also stores the |
| 39 |
-- line number where it appears. |
|
| 64 | -- line number where it appears. The key names and values found in | |
| 65 | -- 'vName' and 'vValue' respectively are _not_ normalized to | |
| 66 | -- lower-case or stripped of whitespace, and thus should appear | |
| 67 | -- exactly as they appear in the original source file. | |
| 40 | 68 | data IniValue = IniValue |
| 41 | 69 | { vLineNo :: Int |
| 70 | -- ^ The line on which the key/value mapping | |
| 71 | -- appears. This field is ignored when | |
| 72 | -- serializing, and is only used for error | |
| 73 | -- messages produced when parsing and | |
| 74 | -- deserializing an INI structure. | |
| 42 | 75 | , vName :: Text |
| 76 | -- ^ The name of the key, as it appears in the INI source. | |
| 43 | 77 | , vValue :: Text |
| 78 | -- ^ The value of the key | |
| 44 | 79 | , vComments :: Seq BlankLine |
| 45 | 80 | , vCommentedOut :: Bool |
| 46 | 81 | -- ^ Right now, this will never show up in a parsed INI file, but |
| 57 | 92 | | BlankLine |
| 58 | 93 | deriving (Eq, Show) |
| 59 | 94 | |
| 60 |
-- | Parse a 'Text' value into an 'Ini' value |
|
| 95 | -- | Parse a 'Text' value into an 'Ini' value, retaining a maximal | |
| 96 | -- amount of structure as needed to reconstruct the original INI file. | |
| 61 | 97 | parseIni :: Text -> Either String Ini |
| 62 | 98 | parseIni t = case runParser pIni "ini file" t of |
| 63 | 99 | Left err -> Left (parseErrorPretty err) |
| 134 | 170 | getCurrentLine = (fromIntegral . unPos . sourceLine) `fmap` getPosition |
| 135 | 171 | |
| 136 | 172 | |
| 173 | -- | Serialize an INI file to text, complete with any comments which | |
| 174 | -- appear in the INI structure, and retaining the aesthetic details | |
| 175 | -- which are present in the INI file. | |
| 137 | 176 | printIni :: Ini -> Text |
| 138 | 177 | printIni = LazyText.toStrict . Builder.toLazyText . F.foldMap build . fromIni |
| 139 | 178 | where |
| 153 | 192 | Builder.singleton (vDelimiter val) <> |
| 154 | 193 | Builder.fromText (vValue val) <> |
| 155 | 194 | Builder.singleton '\n' |
| 195 | ||
| 196 | -- | $main | |
| 197 | -- This module is subject to change in the future, and therefore | |
| 198 | -- should not be relied upon to have a consistent API. | |