config-ini-0.2.4.0: A library for simple INI-based configuration files.

Copyright | (c) Getty Ritter 2017
License | BSD
Maintainer | Getty Ritter <config-ini@infinitenegativeutility.com>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

Data.Ini.Config.Raw

Contents

- INI types
- serializing and deserializing
- inspection

Description

Warning! This module is subject to change in the future, and therefore should not be relied upon to have a consistent API.

Synopsis

- newtype RawIni = RawIni {
  - fromRawIni :: Seq (NormalizedText, IniSection)
  }
- data IniSection = IniSection {
  - isName :: Text
  - isVals :: Seq (NormalizedText, IniValue)
  - isStartLine :: Int
  - isEndLine :: Int
  - isComments :: Seq BlankLine
  }
- data IniValue = IniValue {
  - vLineNo :: Int
  - vName :: Text
  - vValue :: Text
  - vComments :: Seq BlankLine
  - vCommentedOut :: Bool
  - vDelimiter :: Char
  }
- data BlankLine
  - = CommentLine Char Text
  - | BlankLine
- data NormalizedText = NormalizedText {
  - actualText :: Text
  - normalizedText :: Text
  }
- normalize :: Text -> NormalizedText
- parseRawIni :: Text -> Either String RawIni
- printRawIni :: RawIni -> Text
- lookupInSection :: Text -> Text -> RawIni -> Seq Text
- lookupSection :: Text -> RawIni -> Seq IniSection
- lookupValue :: Text -> IniSection -> Seq IniValue

# INI types

newtype RawIni Source #

An `Ini` value is a mapping from section names to `IniSection` 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.

Constructors

RawIni |

Fields

- fromRawIni :: Seq (NormalizedText, IniSection)

Instances

Eq RawIni Source # |
Instance details Defined in Data.Ini.Config.Raw Methods (==) :: RawIni -> RawIni -> Bool Source # (/=) :: RawIni -> RawIni -> Bool Source #
Show RawIni Source # |
Instance details Defined in Data.Ini.Config.Raw Methods showsPrec :: Int -> RawIni -> ShowS Source # show :: RawIni -> String Source # showList :: [RawIni] -> ShowS Source #

data IniSection Source #

An `IniSection` 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 `isName` are not normalized to lower-case or stripped of whitespace, and thus should appear exactly as they appear in the original source file.

Constructors

IniSection |

Fields

- isName :: Text

  The name of the section, as it appears in the original INI source

- isVals :: Seq (NormalizedText, IniValue)

  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.

- isStartLine :: Int

  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.

- isEndLine :: 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.

- isComments :: Seq BlankLine

  The blank lines and comments that appear prior to the section head declaration, retained for pretty-printing identical INI files.

Instances

Eq IniSection Source # |
Instance details Defined in Data.Ini.Config.Raw Methods (==) :: IniSection -> IniSection -> Bool Source # (/=) :: IniSection -> IniSection -> Bool Source #
Show IniSection Source # |
Instance details Defined in Data.Ini.Config.Raw Methods showsPrec :: Int -> IniSection -> ShowS Source # show :: IniSection -> String Source # showList :: [IniSection] -> ShowS Source #

data IniValue Source #

An `IniValue` represents a key-value mapping, and also stores the line number where it appears. The key names and values found in `vName` and `vValue` respectively are _not_ normalized to lower-case or stripped of whitespace, and thus should appear exactly as they appear in the original source file.

Constructors

IniValue |

Fields

- vLineNo :: Int

  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.

- vName :: Text

  The name of the key, as it appears in the INI source.

- vValue :: Text

  The value of the key

- vComments :: Seq BlankLine
- vCommentedOut :: Bool

  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.

- vDelimiter :: Char

Instances

Eq IniValue Source # |
Instance details Defined in Data.Ini.Config.Raw Methods (==) :: IniValue -> IniValue -> Bool Source # (/=) :: IniValue -> IniValue -> Bool Source #
Show IniValue Source # |
Instance details Defined in Data.Ini.Config.Raw Methods showsPrec :: Int -> IniValue -> ShowS Source # show :: IniValue -> String Source # showList :: [IniValue] -> ShowS Source #

data BlankLine Source #

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.

Constructors

CommentLine Char Text |
BlankLine |

Instances

Eq BlankLine Source # |
Instance details Defined in Data.Ini.Config.Raw Methods (==) :: BlankLine -> BlankLine -> Bool Source # (/=) :: BlankLine -> BlankLine -> Bool Source #
Show BlankLine Source # |
Instance details Defined in Data.Ini.Config.Raw Methods showsPrec :: Int -> BlankLine -> ShowS Source # show :: BlankLine -> String Source # showList :: [BlankLine] -> ShowS Source #

data NormalizedText Source #

The `NormalizedText` 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 `Eq` and `Ord` operations, so

      normalize "  x  " == normalize "X"

This type is used to store section and key names in the

Constructors

NormalizedText |

Fields

- actualText :: Text
- normalizedText :: Text

Instances

Eq NormalizedText Source # |
Instance details Defined in Data.Ini.Config.Raw Methods (==) :: NormalizedText -> NormalizedText -> Bool Source # (/=) :: NormalizedText -> NormalizedText -> Bool Source #
Ord NormalizedText Source # |

Instance details

Defined in Data.Ini.Config.Raw

Methods

compare :: NormalizedText -> NormalizedText -> Ordering Source #

(<) :: NormalizedText -> NormalizedText -> Bool Source #

(<=) :: NormalizedText -> NormalizedText -> Bool Source #

(>) :: NormalizedText -> NormalizedText -> Bool Source #

(>=) :: NormalizedText -> NormalizedText -> Bool Source #

max :: NormalizedText -> NormalizedText -> NormalizedText Source #

min :: NormalizedText -> NormalizedText -> NormalizedText Source #

Show NormalizedText Source # |
Instance details Defined in Data.Ini.Config.Raw Methods showsPrec :: Int -> NormalizedText -> ShowS Source # show :: NormalizedText -> String Source # showList :: [NormalizedText] -> ShowS Source #

normalize :: Text -> NormalizedText Source #

The constructor function to build a `NormalizedText` 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 `NormalizedText` values.

# serializing and deserializing

parseRawIni :: Text -> Either String RawIni Source #

Parse a `Text` value into an `Ini` value, retaining a maximal amount of structure as needed to reconstruct the original INI file.

printRawIni :: RawIni -> Text Source #

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.

# inspection

lookupInSection Source #

Arguments

:: Text | The section name. Will be normalized prior to comparison.
-> Text | The key. Will be normalized prior to comparison.
-> RawIni | The Ini to search.
-> Seq Text |

Look up an Ini value by section name and key. Returns the sequence of matches.

lookupSection Source #

Arguments

:: Text | The section name. Will be normalized prior to comparison.
-> RawIni | The Ini to search.
-> Seq IniSection |

Look up an Ini section by name. Returns a sequence of all matching section records.

lookupValue Source #

Arguments

:: Text | The key. Will be normalized prior to comparison.
-> IniSection | The section to search.
-> Seq IniValue |

Look up an Ini key's value in a given section by the key. Returns the sequence of matches.