Data.Ini.List

Most ini config files turn into 1-1 maps quite nicely. However, some encode lists of objects, which require having more than one section of a given name, or more than one value in a section with a given name - and order matters.

This package parsers Ini files, but instead of creating maps, it creates a list of sections, each section of which is a list of values. As a result, the get function can now return a list of values for options that can occur multiple times, and there are plural versions of the Option and Section fetchers.

Types

type Section = AList OptionName Option

A Section is just an AList.

data Config

A config is an unmaned Section and an AList of SectionItems.

Instances

Show Config

Monoid Config

Config as a Monoid is a bit off. The default sections are append to each other. This is required for it to obey the Monoid laws.

type OptionName = String

type SectionName = String

Names are all Strings.

type Option = String

As are values.

type SectionItem = (OptionName, Option)

type ConfigItem = (SectionName, Section)

Convient names for items from a Section or Config

type UpdateValue = SectionName -> OptionName -> Option -> Maybe Option

An UpdateValue is a function that takes a SectionName, OptionName and Option and returns a Nothing if it doesn't want to change the given SectionItem, or Just Option if it does.

type UpdateOption = SectionName -> OptionName -> Option -> Maybe SectionItem

An UpdateOption is like an UpdateValue, except it returns a Maybe SectionItem, allowing it to change the key as well as the value of the SectionItem in question.

class Value a where

The Value class is one that the get functions can return. Most notably, names that occur multiple times in a section can become a List, returning a singleton or empty List for single or missing names in a context where a List is needed.

0/1, yes/no, on/off, true/false and enabled/disabled values will be returned as Bool in the appropriate contexts.

Finally, any value that has a Read instance will be converted if possible, so that integer and floating point values can be used immediately.

Minimal complete definition

value

Methods

getValue :: OptionName -> Section -> Maybe a

getValue Section OptionName gets the value for the named Option from the Section.

value :: Option -> a

value converts a single Option String into a value of the type of the instance.

Instances

Value Bool

Value String

Read t => Value t

Value t => Value [t]

Build

config :: Section -> [ConfigItem] -> Config

config creates a Config from the given default Section and list of ConfigItem's.

setDefault :: Config -> Section -> Config

setDefault sets the default Section for the Config.

(<+) :: Cons container item => container -> item -> container infixl 7

(+>) :: Cons container item => item -> container -> container infixr 7

(+>) and (<+) operators add items to a Config or Section

Convert

toList :: Cons container item => container -> [item]

toList returns the AList in the Config or Section as a list of items.

fromList :: Cons container item => [item] -> container

fromList creates a Config or Section from a list of items. A Config gets an empty default section.

Query

get :: Value a => Config -> Maybe SectionName -> OptionName -> Maybe a

get a value from a Config selected by Maybe SectionName and OptionName. Nothing as the SectionName gets Option values from the default Section.

getDefault :: Config -> Section

getDefault returns the default section from a Config.

getSection :: Config -> SectionName -> Maybe Section

getSection returns the first Section name from Config if one exists.

getSections :: Config -> SectionName -> [Section]

getSections returns the List of Sections with name in the Config.

getSectionsBy :: Config -> (SectionName -> Bool) -> [ConfigItem]

getSectionsBy returns a list of ConfigItem's from a Config chosen by the provided function.

Update

updateValues :: UpdateValue -> Config -> Config

updateOptions uses an UpdateValue to update all the values in the Config.

updateDefaultValues :: (OptionName -> Option -> Maybe Option) -> Config -> Config

updateDefaultOptions updates the values in the default Section of the Config with the given function, which is similar to an UpdateValue without the SectionName argument.

updateSectionValues :: (OptionName -> Option -> Maybe Option) -> Section -> Section

updateSectionValues updates the values in the named Section of the Config with the given function, which is similar to an UpdateValue without the SectionName argument.

updateOptions :: UpdateOption -> Config -> Config

updateOptions uses an UpdateOption to update all the options in the Config.

updateDefaultOptions :: (OptionName -> Option -> Maybe SectionItem) -> Config -> Config

updateDefaultOptions updates the options in the default Section of the Config with the given function, which is similar to an UpdateOption without the SectionName argument.

updateSectionOptions :: (OptionName -> Option -> Maybe SectionItem) -> Section -> Section

updateSectionOptions updates the options in the named Section Section of the Config with the given function, which is similar to an UpdateOption without the SectionName argument.

Format

formatConfig :: Config -> String

formatConfig converts a Config to a String representation for use in a .ini file.

writeConfig :: Config -> IO ()

writeConfig formats a Config and writes it to stdout.

writeConfigFile :: FilePath -> Config -> IO ()

writeConfigFile formats a Config and writes it to FilePath.

hWriteConfig :: Handle -> Config -> IO ()

hwriteConfigFile formats a Config and writes it to a Handle.

Parse

parseConfig :: String -> Result Config

parseConfig parses a String into a Config, returning the Config wrapped in a a Result

parseFile :: FilePath -> IO (Maybe Config)

parseFile parses the named .ini file, sending diagnostic messages to the console.

parseFileEx :: FilePath -> IO (Result Config)

parseFileEx parses the named .ini file, returning either the Config or diagnostic messages in the Result.