ini-0.4.2: Configuration files in the INI format.

Safe Haskell | None
Language | Haskell98

Data.Ini

Contents

- Reading
- Writing
- Advanced writing
- Types
- Parsers

Description

Clean configuration files in the INI format.

Format rules and recommendations:

- The `:` syntax is space-sensitive.
- Keys are case-sensitive.
- Lower-case is recommended.
- Values can be empty.
- Keys cannot key separators, section delimiters, or comment markers.
- Comments must start at the beginning of the line and start with `;` or `#`.

An example configuration file:

    # Some comment.
    [SERVER]
    port=6667
    hostname=localhost
    ; another comment here
    [AUTH]
    user: hello
    pass: world
    salt:

Parsing example:

    >>> parseIni "[SERVER]\nport: 6667\nhostname: localhost"
    Right (Ini {unIni = fromList [("SERVER",fromList [("hostname","localhost"),("port","6667")])]})

Synopsis

- readIniFile :: FilePath -> IO (Either String Ini)
- parseIni :: Text -> Either String Ini
- lookupValue :: Text -> Text -> Ini -> Either String Text
- lookupArray :: Text -> Text -> Ini -> Either String [Text]
- readValue :: Text -> Text -> (Text -> Either String (a, Text)) -> Ini -> Either String a
- readArray :: Text -> Text -> (Text -> Either String (a, Text)) -> Ini -> Either String [a]
- parseValue :: Text -> Text -> Parser a -> Ini -> Either String a
- sections :: Ini -> [Text]
- keys :: Text -> Ini -> Either String [Text]
- printIni :: Ini -> Text
- writeIniFile :: FilePath -> Ini -> IO ()
- data KeySeparator
  - = ColonKeySeparator
  - | EqualsKeySeparator
- data WriteIniSettings = WriteIniSettings {
  - writeIniKeySeparator :: KeySeparator
  }
- defaultWriteIniSettings :: WriteIniSettings
- printIniWith :: WriteIniSettings -> Ini -> Text
- writeIniFileWith :: WriteIniSettings -> FilePath -> Ini -> IO ()
- data Ini = Ini {
  - iniSections :: HashMap Text [(Text, Text)]
  - iniGlobals :: [(Text, Text)]
  }
- unIni :: Ini -> HashMap Text (HashMap Text Text)
- iniParser :: Parser Ini
- sectionParser :: Parser (Text, [(Text, Text)])
- keyValueParser :: Parser (Text, Text)

# Reading

readIniFile :: FilePath -> IO (Either String Ini) Source #

Parse an INI file.

parseIni :: Text -> Either String Ini Source #

Parse an INI config.

lookupValue Source #

Arguments

:: Text | Section name
-> Text | Key
-> Ini |
-> Either String Text |

Lookup one value in the config.

Example:

    >>> parseIni "[SERVER]\nport: 6667\nhostname: localhost" >>= lookupValue "SERVER" "hostname"
    Right "localhost"

lookupArray Source #

Arguments

:: Text | Section name
-> Text | Key
-> Ini |
-> Either String [Text] |

Lookup one value in the config.

Example:

    >>> parseIni "[SERVER]\nport: 6667\nhostname: localhost" >>= lookupValue "SERVER" "hostname"
    Right "localhost"

readValue Source #

Arguments

:: Text | Section name
-> Text | Key
-> (Text -> Either String (a, Text)) |
-> Ini |
-> Either String a |

Read a value using a reader from Data.Text.Read.

readArray Source #

Arguments

:: Text | Section name
-> Text | Key
-> (Text -> Either String (a, Text)) |
-> Ini |
-> Either String [a] |

Read an array of values using a reader from Data.Text.Read.

parseValue Source #

Arguments

:: Text | Section name
-> Text | Key
-> Parser a |
-> Ini |
-> Either String a |

Parse a value using a reader from Data.Attoparsec.Text.

sections :: Ini -> [Text] Source #

Get the sections in the config.

Example:

    >>> sections <$> parseIni "[SERVER]\nport: 6667\nhostname: localhost"
    Right ["SERVER"]

keys Source #

Arguments

:: Text | Section name
-> Ini |
-> Either String [Text] |

Get the keys in a section.

Example:

    >>> parseIni "[SERVER]\nport: 6667\nhostname: localhost" >>= keys "SERVER"
    Right ["hostname","port"]

# Writing

printIni :: Ini -> Text Source #

Print an INI config.

writeIniFile :: FilePath -> Ini -> IO () Source #

Print the INI config to a file.

# Advanced writing

data KeySeparator Source #

Either `:` or `=`.

Constructors

ColonKeySeparator |
EqualsKeySeparator |

#### Instances

Instances details

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

data WriteIniSettings Source #

Settings determining how an INI file is written.

Constructors

WriteIniSettings |

Fields

- writeIniKeySeparator :: KeySeparator

#### Instances

Instances details

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

defaultWriteIniSettings :: WriteIniSettings Source #

The default settings for writing INI files.

printIniWith :: WriteIniSettings -> Ini -> Text Source #

Print an INI config.

writeIniFileWith :: WriteIniSettings -> FilePath -> Ini -> IO () Source #

Print the INI config to a file.

# Types

data Ini Source #

An INI configuration.

Constructors

Ini |

Fields

- iniSections :: HashMap Text [(Text, Text)]
- iniGlobals :: [(Text, Text)]

#### Instances

Instances details

Monoid Ini Source # |
Instance details Defined in Data.Ini Methods mempty :: Ini Source # mappend :: Ini -> Ini -> Ini Source # mconcat :: [Ini] -> Ini Source #
Semigroup Ini Source # |
Instance details Defined in Data.Ini Methods (<>) :: Ini -> Ini -> Ini Source # sconcat :: NonEmpty Ini -> Ini Source # stimes :: Integral b => b -> Ini -> Ini Source #
Show Ini Source # |
Instance details Defined in Data.Ini Methods showsPrec :: Int -> Ini -> ShowS Source # show :: Ini -> String Source # showList :: [Ini] -> ShowS Source #
Eq Ini Source # |
Instance details Defined in Data.Ini Methods (==) :: Ini -> Ini -> Bool Source # (/=) :: Ini -> Ini -> Bool Source #

unIni :: Ini -> HashMap Text (HashMap Text Text) Source #

# Parsers

iniParser :: Parser Ini Source #

Parser for an INI.

sectionParser :: Parser (Text, [(Text, Text)]) Source #

A section. Format: `[foo]`. Conventionally, `[FOO]`.

keyValueParser :: Parser (Text, Text) Source #

A key-value pair. Either `foo: bar` or `foo=bar`.