<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <!--Rendered using the Haskell Html Library v0.2--> <HTML ><HEAD ><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8" ><TITLE >Data.ConfigFile</TITLE ><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css" ><SCRIPT SRC="haddock-util.js" TYPE="text/javascript" ></SCRIPT ><SCRIPT TYPE="text/javascript" >window.onload = function () {setSynopsis("mini_Data-ConfigFile.html")};</SCRIPT ></HEAD ><BODY ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="topbar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" " ></TD ><TD CLASS="title" >ConfigFile-1.0.6: Configuration file reading & writing</TD ><TD CLASS="topbut" ><A HREF="src/Data-ConfigFile.html" >Source code</A ></TD ><TD CLASS="topbut" ><A HREF="index.html" >Contents</A ></TD ><TD CLASS="topbut" ><A HREF="doc-index.html" >Index</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="modulebar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><FONT SIZE="6" >Data.ConfigFile</FONT ></TD ><TD ALIGN="right" ><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="infohead" >Portability</TD ><TD CLASS="infoval" >portable</TD ></TR ><TR ><TD CLASS="infohead" >Stability</TD ><TD CLASS="infoval" >provisional</TD ></TR ><TR ><TD CLASS="infohead" >Maintainer</TD ><TD CLASS="infoval" >John Goerzen <jgoerzen@complete.org></TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="section4" ><B >Contents</B ></TD ></TR ><TR ><TD ><DL ><DT ><A HREF="#1" >Introduction </A ></DT ><DD ><DL ><DT ><A HREF="#2" >Features </A ></DT ><DT ><A HREF="#3" >History </A ></DT ></DL ></DD ><DT ><A HREF="#4" >Configuration File Format </A ></DT ><DD ><DL ><DT ><A HREF="#5" >White Space </A ></DT ><DT ><A HREF="#6" >Comments </A ></DT ><DT ><A HREF="#7" >Case Sensitivity </A ></DT ><DT ><A HREF="#8" >Interpolation </A ></DT ></DL ></DD ><DT ><A HREF="#9" >Usage Examples </A ></DT ><DD ><DL ><DT ><A HREF="#10" >Non-Monadic Usage </A ></DT ><DT ><A HREF="#11" >Error Monad Usage </A ></DT ><DT ><A HREF="#12" >Combined Error/IO Monad Usage </A ></DT ></DL ></DD ><DT ><A HREF="#13" >Types </A ></DT ><DT ><A HREF="#14" >Initialization </A ></DT ><DT ><A HREF="#15" >Configuring the ConfigParser </A ></DT ><DD ><DL ><DT ><A HREF="#16" >Access Functions </A ></DT ></DL ></DD ><DT ><A HREF="#17" >Reading </A ></DT ><DT ><A HREF="#18" >Accessing Data </A ></DT ><DT ><A HREF="#19" >Modifying Data </A ></DT ><DT ><A HREF="#20" >Output Data </A ></DT ></DL ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Description</TD ></TR ><TR ><TD CLASS="doc" ><P >Configuration file parsing, generation, and manipulation </P ><P >Copyright (c) 2004-2008 John Goerzen, jgoerzen@complete.org </P ><P >This module contains extensive documentation. Please scroll down to the Introduction section to continue reading. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Synopsis</TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >type</SPAN > <A HREF="#t%3ASectionSpec" >SectionSpec</A > = <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >type</SPAN > <A HREF="#t%3AOptionSpec" >OptionSpec</A > = <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >data</SPAN > <A HREF="#t%3AConfigParser" >ConfigParser</A > = <A HREF="#v%3AConfigParser" >ConfigParser</A > {<TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="recfield" ><A HREF="#v%3Acontent" >content</A > :: <A HREF="Data-ConfigFile-Types.html#t%3ACPData" >CPData</A ></TD ></TR ><TR ><TD CLASS="recfield" ><A HREF="#v%3Aoptionxform" >optionxform</A > :: <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A ></TD ></TR ><TR ><TD CLASS="recfield" ><A HREF="#v%3Adefaulthandler" >defaulthandler</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Either.html#t%3AEither" >Either</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="recfield" ><A HREF="#v%3Ausedefault" >usedefault</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ></TR ><TR ><TD CLASS="recfield" ><A HREF="#v%3Aaccessfunc" >accessfunc</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Either.html#t%3AEither" >Either</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ></TABLE >}</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >data</SPAN > <A HREF="#t%3ACPErrorData" >CPErrorData</A > </TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" >= <A HREF="#v%3AParseError" >ParseError</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="decl" >| <A HREF="#v%3ASectionAlreadyExists" >SectionAlreadyExists</A > <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A ></TD ></TR ><TR ><TD CLASS="decl" >| <A HREF="#v%3ANoSection" >NoSection</A > <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A ></TD ></TR ><TR ><TD CLASS="decl" >| <A HREF="#v%3ANoOption" >NoOption</A > <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A ></TD ></TR ><TR ><TD CLASS="decl" >| <A HREF="#v%3AOtherProblem" >OtherProblem</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="decl" >| <A HREF="#v%3AInterpolationError" >InterpolationError</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >type</SPAN > <A HREF="#t%3ACPError" >CPError</A > = (<A HREF="Data-ConfigFile.html#t%3ACPErrorData" >CPErrorData</A >, <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A >)</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AemptyCP" >emptyCP</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AsimpleAccess" >simpleAccess</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AinterpolatingAccess" >interpolatingAccess</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Areadfile" >readfile</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/MissingH-1.1.0.3/System-IO-HVFS.html#t%3AFilePath" >FilePath</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > (m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A >)</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Areadhandle" >readhandle</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/GHC-IO-Handle.html#t%3AHandle" >Handle</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > (m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A >)</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Areadstring" >readstring</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >class</SPAN > <A HREF="#t%3AGet_C" >Get_C</A > a <SPAN CLASS="keyword" >where</SPAN ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="#v%3Aget" >get</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m a</TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Asections" >sections</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> [<A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A >]</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Ahas_section" >has_section</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aoptions" >options</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m [<A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A >]</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Ahas_option" >has_option</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aitems" >items</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m [(<A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A >, <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A >)]</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aset" >set</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Asetshow" >setshow</A > :: (<A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Text-Show.html#t%3AShow" >Show</A > a, <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m) => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> a -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aremove_option" >remove_option</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aadd_section" >add_section</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aremove_section" >remove_section</A > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Amerge" >merge</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Ato_string" >to_string</A > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="1" ><A NAME="1" >Introduction </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >Many programs need configuration files. These configuration files are typically used to configure certain runtime behaviors that need to be saved across sessions. Various different configuration file formats exist. </P ><P >The ConfigParser module attempts to define a standard format that is easy for the user to edit, easy for the programmer to work with, yet remains powerful and flexible. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="2" ><A NAME="2" >Features </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >For the programmer, this module provides: </P ><UL ><LI > Simple calls to both read <EM >and write</EM > configuration files </LI ><LI > Call that can generate a string version of a file that is re-parsable by this module (useful for, for instance, sending the file down a network) </LI ><LI > Segmented configuration files that let you separate configuration into distinct sections, each with its own namespace. This can be used to configure multiple modules in one file, to configure multiple instances of a single object, etc. </LI ><LI > On-the-fly parsing of integer, boolean, float, multi-line string values, and anything else Haskell's read can deal with </LI ><LI > It is possible to make a configuration file parsable by this module, the Unix shell, and/or Unix make, though some feautres are, of course, not compatible with these other tools. </LI ><LI > Syntax checking with error reporting including line numbers </LI ><LI > Implemented in pure Haskell. No dependencies on modules outside the standard library distributed with Haskell compilers or interpreters. All calls except those that read directly from a handle are pure calls and can be used outside the IO monad. </LI ><LI > Comprehensive documentation </LI ><LI > Extensible API </LI ><LI > Complete compatibility with Python's ConfigParser module, or my ConfigParser module for OCaml, part of my MissingLib package. </LI ></UL ><P >For the user, this module provides: </P ><UL ><LI > Easily human-editable configuration files with a clear, concise, and consistent format </LI ><LI > Configuration file format consistent with other familiar formats (/etc/passwd is a valid ConfigParser file) </LI ><LI > No need to understand semantics of markup languages like XML </LI ></UL ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="3" ><A NAME="3" >History </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >This module is based on Python's ConfigParser module at <A HREF="http://www.python.org/doc/current/lib/module-ConfigParser.html" >http://www.python.org/doc/current/lib/module-ConfigParser.html</A >. I had earlier developed an OCaml implementation as part of my MissingLib library at <A HREF="gopher://gopher.quux.org/devel/missinglib" >gopher://gopher.quux.org/devel/missinglib</A >. </P ><P >While the API of these three modules is similar, and the aim is to preserve all useful features of the original Python module, there are some differences in the implementation details. This module is a complete, clean re-implementation in Haskell, not a Haskell translation of a Python program. As such, the feature set is slightly different. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="4" ><A NAME="4" >Configuration File Format </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >The basic configuration file format resembles that of an old-style Windows .INI file. Here are two samples: </P ><PRE >debug = yes inputfile = /etc/passwd names = Peter, Paul, Mary, George, Abrahaham, John, Bill, Gerald, Richard, Franklin, Woodrow color = red </PRE ><P >This defines a file without any explicit section, so all items will occur within the default section <TT >DEFAULT</TT >. The <TT >debug</TT > option can be read as a boolean or a string. The remaining items can be read as a string only. The <TT >names</TT > entry spans two lines -- any line starting with whitespace, and containing something other than whitespace or comments, is taken as a continuation of the previous line. </P ><P >Here's another example: </P ><PRE ># Default options [DEFAULT] hostname: localhost # Options for the first file [file1] location: /usr/local user: Fred uid: 1000 optionaltext: Hello, this entire string is included [file2] location: /opt user: Fred uid: 1001 </PRE ><P >This file defines three sections. The <TT >DEFAULT</TT > section specifies an entry <TT >hostname</TT >. If you attempt to read the hostname option in any section, and that section doesn't define <TT >hostname</TT >, you will get the value from <TT >DEFAULT</TT > instead. This is a nice time-saver. You can also note that you can use colons instead of the = character to separate option names from option entries. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="5" ><A NAME="5" >White Space </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >Whitespace (spaces, tabs, etc) is automatically stripped from the beginning and end of all strings. Thus, users can insert whitespace before/after the colon or equal sign if they like, and it will be automatically stripped. </P ><P >Blank lines or lines consisting solely of whitespace are ignored. </P ><P >A line giving an option or a section name may not begin with white space. This requirement is necessary so there is no ambiguity between such lines and continuation lines for multi-line options. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="6" ><A NAME="6" >Comments </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >Comments are introduced with the pound sign <TT >#</TT > or the semicolon <TT >;</TT >. They cause the parser to ignore everything from that character to the end of the line. </P ><P >Comments <EM >may not</EM > occur within the definitions of options; that is, you may not place a comment in the middle of a line such as <TT >user: Fred</TT >. That is because the parser considers the comment characters part of the string; otherwise, you'd be unable to use those characters in your strings. You can, however, "comment out" options by putting the comment character at the start of the line. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="7" ><A NAME="7" >Case Sensitivity </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" >By default, section names are case-sensitive but option names are not. The latter can be adjusted by adjusting <TT ><A HREF="Data-ConfigFile.html#v%3Aoptionxform" >optionxform</A ></TT >. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="8" ><A NAME="8" >Interpolation </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >Interpolation is an optional feature, disabled by default. If you replace the default <TT ><A HREF="Data-ConfigFile.html#v%3Aaccessfunc" >accessfunc</A ></TT > (<TT ><A HREF="Data-ConfigFile.html#v%3AsimpleAccess" >simpleAccess</A ></TT >) with <TT ><A HREF="Data-ConfigFile.html#v%3AinterpolatingAccess" >interpolatingAccess</A ></TT >, then you get interpolation support with <TT ><A HREF="Data-ConfigFile.html#v%3Aget" >get</A ></TT > and the other <TT ><A HREF="Data-ConfigFile.html#v%3Aget" >get</A ></TT >-based functions. </P ><P >As an example, consider the following file: </P ><PRE >arch = i386 project = test filename = test_%(arch)s.c dir = /usr/src/%(filename)s percent = 5%% </PRE ><P >With interpolation, you would get these results: </P ><PRE >get cp "DEFAULT" "filename" -> "test_i386.c" get cp "DEFAULT" "dir" -> "/usr/src/test_i386.c" get cp "DEFAULT" "percent" -> "5%" </PRE ><P >For more details on interpolation, please see the documentation for the <TT ><A HREF="Data-ConfigFile.html#v%3AinterpolatingAccess" >interpolatingAccess</A ></TT > function. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="9" ><A NAME="9" >Usage Examples </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >The basic theory of working with ConfigParser is this: </P ><P >1. Parse or build a <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > object </P ><P >2. Work with it in one of several ways </P ><P >3. To make changes, you discard the original object and use a new one. Changes can be <A HREF="chained.html" >chained</A > through one of several monads. </P ><P >The default <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > object that you always start with is <TT ><A HREF="Data-ConfigFile.html#v%3AemptyCP" >emptyCP</A ></TT >. From here, you load data into it (merging data into the empty object), set up structures yourself, or adjust options. </P ><P >Let's take a look at some basic use cases. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="10" ><A NAME="10" >Non-Monadic Usage </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >You'll notice that many functions in this module return a <TT >MonadError <TT ><A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A ></TT ></TT > over some type. Although its definition is not this simple, you can consider this to be the same as returning <TT >Either CPError a</TT >. </P ><P >That is, these functions will return <TT >Left error</TT > if there's a problem or <TT >Right result</TT > if things are fine. The documentation for individual functions describes the specific circumstances in which an error may occur in more detail. </P ><P >Some people find it annoying to have to deal with errors manually. You can transform errors into exceptions in your code by using <TT ><A HREF="/usr/share/doc/ghc/html/libraries/MissingH-1.1.0.3/Data-Either-Utils.html#v%3AforceEither" >forceEither</A ></TT >. Here's an example of this style of programming: </P ><PRE > import Data.Either.Utils do val <- readfile emptyCP "/etc/foo.cfg" let cp = forceEither val putStrLn "Your setting is:" putStrLn $ forceEither $ get cp "sect1" "opt1" </PRE ><P >In short, you can just put <TT >forceEither $</TT > in front of every call that returns something that is a MonadError. This is still a pure functional call, so it can be used outside of the IO monads. The exception, however, can only be caught in the IO monad. </P ><P >If you don't want to bother with <TT ><A HREF="/usr/share/doc/ghc/html/libraries/MissingH-1.1.0.3/Data-Either-Utils.html#v%3AforceEither" >forceEither</A ></TT >, you can use the error monad. It's simple and better... read on. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="11" ><A NAME="11" >Error Monad Usage </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >The return type is actually defined in terms of the Error monad, which is itself based on the Either data type. </P ><P >Here's a neat example of chaining together calls to build up a <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > object: </P ><PRE >do let cp = emptyCP cp <- add_section cp "sect1" cp <- set cp "sect1" "opt1" "foo" cp <- set cp "sect1" "opt2" "bar" options cp "sect1" </PRE ><P >The return value of this little snippet is <TT >Right ["opt1", "opt2"]</TT >. (Note to beginners: unlike the IO monad, you <EM >can</EM > escape from the Error monad.) </P ><P >Although it's not obvious, there actually was error checking there. If any of those calls would have generated an error, processing would have stopped immediately and a <TT >Left</TT > value would have been returned. Consider this example: </P ><PRE >do let cp = emptyCP cp <- add_section cp "sect1" cp <- set cp "sect1" "opt1" "foo" cp <- set cp "sect2" "opt2" "bar" options cp "sect1" </PRE ><P >The return value from this is <TT >Left (<TT ><A HREF="Data-ConfigFile.html#v%3ANoSection" >NoSection</A ></TT > "sect2", "set")</TT >. The second call to <TT ><A HREF="Data-ConfigFile.html#v%3Aset" >set</A ></TT > failed, so the final call was skipped, and the result of the entire computation was considered to be an error. </P ><P >You can combine this with the non-monadic style to get a final, pure value out of it: </P ><PRE >forceEither $ do let cp = emptyCP cp <- add_section cp "sect1" cp <- set cp "sect1" "opt1" "foo" cp <- set cp "sect1" "opt2" "bar" options cp "sect1" </PRE ><P >This returns <TT >["opt1", "opt2"]</TT >. A quite normal value. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="12" ><A NAME="12" >Combined Error/IO Monad Usage </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >You've seen a nice way to use this module in the Error monad and get an Either value out. But that's the Error monad, so IO is not permitted. Using Haskell's monad transformers, you can run it in the combined Error/IO monad. That is, you will get an IO result back. Here is a full standalone example of doing that: </P ><PRE >import Data.ConfigFile import Control.Monad.Error main = do rv <- runErrorT $ do cp <- join $ liftIO $ readfile empty "/etc/passwd" let x = cp liftIO $ putStrLn "In the test" nb <- get x "DEFAULT" "nobody" liftIO $ putStrLn nb foo <- get x "DEFAULT" "foo" liftIO $ putStrLn foo return "done" print rv </PRE ><P >On my system, this prints: </P ><PRE >In the test x:65534:65534:nobody:/nonexistent:/bin/sh Left (NoOption "foo","get") </PRE ><P >That is, my <TT >/etc/passwd</TT > file contains a <TT >nobody</TT > user but not a <TT >foo</TT > user. </P ><P >Let's look at how that works. </P ><P >First, <TT >main</TT > always runs in the IO monad only, so we take the result from the later calls and put it in <TT >rv</TT >. Note that the combined block is started with <TT >runErrorT $ do</TT > instead of just <TT >do</TT >. </P ><P >To get something out of the call to <TT ><A HREF="Data-ConfigFile.html#v%3Areadfile" >readfile</A ></TT >, we use <TT >join $ liftIO $ readfile</TT >. This will bring the result out of the IO monad into the combined monad and process it like usual. From here on, everything looks normal, except for IO calls. They are all executed under <TT >liftIO</TT > so that the result value is properly brought into the combined monad. This finally returns <TT >"done"</TT >. Since we are in the Error monad, that means that the literal value is <TT >Right "done"</TT >. Since we are also in the IO monad, this is wrapped in IO. So the final return type after applying <TT >runErrorT</TT > is <TT >IO (Either CPError String)</TT >. </P ><P >In this case, there was an error, and processing stopped at that point just like the example of the pure Error monad. We print out the return value, so you see the error displayed as a <TT >Left</TT > value. </P ><P >It all works quite easily. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="13" ><A NAME="13" >Types </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >The code used to say this: </P ><PRE >type CPResult a = MonadError CPError m => m a simpleAccess :: ConfigParser -> SectionSpec -> OptionSpec -> CPResult String </PRE ><P >But Hugs did not support that type declaration. Therefore, types are now given like this: </P ><PRE >simpleAccess :: MonadError CPError m => ConfigParser -> SectionSpec -> OptionSpec -> m String </PRE ><P >Although it looks more confusing than before, it still means the same. The return value can still be treated as <TT >Either CPError String</TT > if you so desire. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><SPAN CLASS="keyword" >type</SPAN > <A NAME="t:SectionSpec" ><A NAME="t%3ASectionSpec" ></A ></A ><B >SectionSpec</B > = <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile-Types.html#SectionSpec" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Names of sections </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><SPAN CLASS="keyword" >type</SPAN > <A NAME="t:OptionSpec" ><A NAME="t%3AOptionSpec" ></A ></A ><B >OptionSpec</B > = <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile-Types.html#OptionSpec" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Names of options </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><SPAN CLASS="keyword" >data</SPAN > <A NAME="t:ConfigParser" ><A NAME="t%3AConfigParser" ></A ></A ><B >ConfigParser</B > </TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile-Types.html#ConfigParser" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="ndoc" >This is the main record that is used by Data.ConfigFile. </TD ></TR ><TR ><TD CLASS="section4" >Constructors</TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="5" CELLPADDING="0" ><TR ><TD CLASS="arg" ><A NAME="v:ConfigParser" ><A NAME="v%3AConfigParser" ></A ></A ><B >ConfigParser</B ></TD ><TD CLASS="rdoc" ></TD ></TR ><TR ><TD CLASS="body" COLSPAN="2" ><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0" ><TR ><TD CLASS="arg" ><A NAME="v:content" ><A NAME="v%3Acontent" ></A ></A ><B >content</B > :: <A HREF="Data-ConfigFile-Types.html#t%3ACPData" >CPData</A ></TD ><TD CLASS="rdoc" >The data itself </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:optionxform" ><A NAME="v%3Aoptionxform" ></A ></A ><B >optionxform</B > :: <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A ></TD ><TD CLASS="rdoc" >How to transform an option into a standard representation </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:defaulthandler" ><A NAME="v%3Adefaulthandler" ></A ></A ><B >defaulthandler</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Either.html#t%3AEither" >Either</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="rdoc" >Function to look up an option, considering a default value if <TT ><A HREF="Data-ConfigFile.html#v%3Ausedefault" >usedefault</A ></TT > is True; or ignoring a default value otherwise. The option specification is assumed to be already transformed. </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:usedefault" ><A NAME="v%3Ausedefault" ></A ></A ><B >usedefault</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ><TD CLASS="rdoc" >Whether or not to seek out a default action when no match is found. </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:accessfunc" ><A NAME="v%3Aaccessfunc" ></A ></A ><B >accessfunc</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Either.html#t%3AEither" >Either</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="rdoc" >Function that is used to perform lookups, do optional interpolation, etc. It is assumed that accessfunc will internally call defaulthandler to do the underlying lookup. The option value is not assumed to be transformed. </TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><SPAN CLASS="keyword" >data</SPAN > <A NAME="t:CPErrorData" ><A NAME="t%3ACPErrorData" ></A ></A ><B >CPErrorData</B > </TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile-Types.html#CPErrorData" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="ndoc" >Possible ConfigParser errors. </TD ></TR ><TR ><TD CLASS="section4" >Constructors</TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0" ><TR ><TD CLASS="arg" ><A NAME="v:ParseError" ><A NAME="v%3AParseError" ></A ></A ><B >ParseError</B > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="rdoc" >Parse error </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:SectionAlreadyExists" ><A NAME="v%3ASectionAlreadyExists" ></A ></A ><B >SectionAlreadyExists</B > <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A ></TD ><TD CLASS="rdoc" >Attempt to create an already-existing ection </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:NoSection" ><A NAME="v%3ANoSection" ></A ></A ><B >NoSection</B > <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A ></TD ><TD CLASS="rdoc" >The section does not exist </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:NoOption" ><A NAME="v%3ANoOption" ></A ></A ><B >NoOption</B > <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A ></TD ><TD CLASS="rdoc" >The option does not exist </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:OtherProblem" ><A NAME="v%3AOtherProblem" ></A ></A ><B >OtherProblem</B > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="rdoc" >Miscellaneous error </TD ></TR ><TR ><TD CLASS="arg" ><A NAME="v:InterpolationError" ><A NAME="v%3AInterpolationError" ></A ></A ><B >InterpolationError</B > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="rdoc" >Raised by Data.ConfigFile.interpolatingAccess if a request was made for a non-existant option </TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="section4" ><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:CPErrorData')" ALT="show/hide" > Instances</TD ></TR ><TR ><TD CLASS="body" ><DIV ID="i:CPErrorData" STYLE="display:block;" ><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Eq.html#t%3AEq" >Eq</A > <A HREF="Data-ConfigFile.html#t%3ACPErrorData" >CPErrorData</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Ord.html#t%3AOrd" >Ord</A > <A HREF="Data-ConfigFile.html#t%3ACPErrorData" >CPErrorData</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Text-Show.html#t%3AShow" >Show</A > <A HREF="Data-ConfigFile.html#t%3ACPErrorData" >CPErrorData</A ></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><SPAN CLASS="keyword" >type</SPAN > <A NAME="t:CPError" ><A NAME="t%3ACPError" ></A ></A ><B >CPError</B > = (<A HREF="Data-ConfigFile.html#t%3ACPErrorData" >CPErrorData</A >, <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A >)</TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile-Types.html#CPError" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Indicates an error occurred. The String is an explanation of the location of the error. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="14" ><A NAME="14" >Initialization </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:emptyCP" ><A NAME="v%3AemptyCP" ></A ></A ><B >emptyCP</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#emptyCP" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >The default empty Data.ConfigFile object. </P ><P >The content contains only an empty mandatory <TT >DEFAULT</TT > section. </P ><P ><TT ><A HREF="Data-ConfigFile.html#v%3Aoptionxform" >optionxform</A ></TT > is set to <TT >map toLower</TT >. </P ><P ><TT ><A HREF="Data-ConfigFile.html#v%3Ausedefault" >usedefault</A ></TT > is set to <TT >True</TT >. </P ><P ><TT ><A HREF="Data-ConfigFile.html#v%3Aaccessfunc" >accessfunc</A ></TT > is set to <TT ><A HREF="Data-ConfigFile.html#v%3AsimpleAccess" >simpleAccess</A ></TT >. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="15" ><A NAME="15" >Configuring the ConfigParser </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >You may notice that the <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > object has some configurable parameters, such as <TT ><A HREF="Data-ConfigFile.html#v%3Ausedefault" >usedefault</A ></TT >. In case you're not familiar with the Haskell syntax for working with these, you can use syntax like this to set these options: </P ><PRE >let cp2 = cp { usedefault = False } </PRE ><P >This will create a new <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > that is the same as <TT >cp</TT > except for the <TT ><A HREF="Data-ConfigFile.html#v%3Ausedefault" >usedefault</A ></TT > field, which is now always False. The new object will be called <TT >cp2</TT > in this example. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="16" ><A NAME="16" >Access Functions </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:simpleAccess" ><A NAME="v%3AsimpleAccess" ></A ></A ><B >simpleAccess</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#simpleAccess" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Default (non-interpolating) access function </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:interpolatingAccess" ><A NAME="v%3AinterpolatingAccess" ></A ></A ><B >interpolatingAccess</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A > -> <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#interpolatingAccess" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Interpolating access function. Please see the Interpolation section above for a background on interpolation. </P ><P >Although the format string looks similar to one used by <A HREF="Text-Printf.html" >Text.Printf</A >, it is not the same. In particular, only the %(...)s format is supported. No width specifiers are supported and no conversions other than s are supported. </P ><P >To use this function, you must specify a maximum recursion depth for interpolation. This is used to prevent a stack overflow in the event that the configuration file contains an endless interpolation loop. Values of 10 or so are usually more than enough, though you could probably go into the hundreds or thousands before you have actual problems. </P ><P >A value less than one will cause an instant error every time you attempt a lookup. </P ><P >This access method can cause <TT ><A HREF="Data-ConfigFile.html#v%3Aget" >get</A ></TT > and friends to return a new <TT ><A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A ></TT >: <TT ><A HREF="Data-ConfigFile.html#v%3AInterpolationError" >InterpolationError</A ></TT >. This error would be returned when: </P ><UL ><LI > The configuration file makes a reference to an option that does not exist </LI ><LI > The maximum interpolation depth is exceeded </LI ><LI > There is a syntax error processing a %-directive in the configuration file </LI ></UL ><P >An interpolation lookup name specifies an option only. There is no provision to specify a section. Interpolation variables are looked up in the current section, and, if <TT ><A HREF="Data-ConfigFile.html#v%3Ausedefault" >usedefault</A ></TT > is True, in <TT >DEFAULT</TT > according to the normal logic. </P ><P >To use a literal percent sign, you must place <TT >%%</TT > in the configuration file when interpolation is used. </P ><P >Here is how you might enable interpolation: </P ><PRE >let cp2 = cp {accessfunc = interpolatingAccess 10} </PRE ><P >The <TT >cp2</TT > object will now support interpolation with a maximum depth of 10. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="17" ><A NAME="17" >Reading </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >You can use these functions to read data from a file. </P ><P >A common idiom for loading a new object from stratch is: </P ><PRE >cp <- <TT ><A HREF="Data-ConfigFile.html#v%3Areadfile" >readfile</A ></TT > <TT ><A HREF="Data-ConfigFile.html#v%3AemptyCP" >emptyCP</A ></TT > "/etc/foo.cfg"</PRE ><P >Note the use of <TT ><A HREF="Data-ConfigFile.html#v%3AemptyCP" >emptyCP</A ></TT >; this will essentially cause the file's data to be merged with the empty <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT >. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:readfile" ><A NAME="v%3Areadfile" ></A ></A ><B >readfile</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/MissingH-1.1.0.3/System-IO-HVFS.html#t%3AFilePath" >FilePath</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > (m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A >)</TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#readfile" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Loads data from the specified file. It is then combined with the given <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > using the semantics documented under <TT ><A HREF="Data-ConfigFile.html#v%3Amerge" >merge</A ></TT > with the new data taking precedence over the old. However, unlike <TT ><A HREF="Data-ConfigFile.html#v%3Amerge" >merge</A ></TT >, all the options as set in the old object are preserved since the on-disk representation does not convey those options. </P ><P >May return an error if there is a syntax error. May raise an exception if the file could not be accessed. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:readhandle" ><A NAME="v%3Areadhandle" ></A ></A ><B >readhandle</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/GHC-IO-Handle.html#t%3AHandle" >Handle</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > (m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A >)</TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#readhandle" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Like <TT ><A HREF="Data-ConfigFile.html#v%3Areadfile" >readfile</A ></TT >, but uses an already-open handle. You should use <TT ><A HREF="Data-ConfigFile.html#v%3Areadfile" >readfile</A ></TT > instead of this if possible, since it will be able to generate better error messages. </P ><P >Errors would be returned on a syntax error. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:readstring" ><A NAME="v%3Areadstring" ></A ></A ><B >readstring</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#readstring" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Like <TT ><A HREF="Data-ConfigFile.html#v%3Areadfile" >readfile</A ></TT >, but uses a string. You should use <TT ><A HREF="Data-ConfigFile.html#v%3Areadfile" >readfile</A ></TT > instead of this if you are processing a file, since it can generate better error messages. </P ><P >Errors would be returned on a syntax error. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="18" ><A NAME="18" >Accessing Data </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><SPAN CLASS="keyword" >class</SPAN > <A NAME="t:Get_C" ><A NAME="t%3AGet_C" ></A ></A ><B >Get_C</B > a <SPAN CLASS="keyword" >where</SPAN ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#Get_C" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="ndoc" >The class representing the data types that can be returned by <A HREF="get.html" >get</A >. </TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="section4" >Methods</TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:get" ><A NAME="v%3Aget" ></A ></A ><B >get</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m a</TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#get" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Retrieves a string from the configuration file. </P ><P >When used in a context where a String is expected, returns that string verbatim. </P ><P >When used in a context where a Bool is expected, parses the string to a Boolean value (see logic below). </P ><P >When used in a context where anything that is an instance of Read is expected, calls read to parse the item. </P ><P >An error will be returned of no such option could be found or if it could not be parsed as a boolean (when returning a Bool). </P ><P >When parsing to a Bool, strings are case-insentively converted as follows: </P ><P >The following will produce a True value: </P ><UL ><LI > 1 </LI ><LI > yes </LI ><LI > on </LI ><LI > enabled </LI ><LI > true </LI ></UL ><P >The following will produce a False value: </P ><UL ><LI > 0 </LI ><LI > no </LI ><LI > off </LI ><LI > disabled </LI ><LI > false </LI ></UL ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="section4" ><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:Get_C')" ALT="show/hide" > Instances</TD ></TR ><TR ><TD CLASS="body" ><DIV ID="i:Get_C" STYLE="display:block;" ><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="Data-ConfigFile.html#t%3AGet_C" >Get_C</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-ConfigFile.html#t%3AGet_C" >Get_C</A > <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Prelude.html#t%3ANum" >Num</A > t, <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Text-Read.html#t%3ARead" >Read</A > t) => <A HREF="Data-ConfigFile.html#t%3AGet_C" >Get_C</A > t</TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:sections" ><A NAME="v%3Asections" ></A ></A ><B >sections</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> [<A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A >]</TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#sections" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Returns a list of sections in your configuration file. Never includes the always-present section <TT >DEFAULT</TT >. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:has_section" ><A NAME="v%3Ahas_section" ></A ></A ><B >has_section</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#has_section" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Indicates whether the given section exists. </P ><P >No special <TT >DEFAULT</TT > processing is done. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:options" ><A NAME="v%3Aoptions" ></A ></A ><B >options</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m [<A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A >]</TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#options" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Returns a list of the names of all the options present in the given section. </P ><P >Returns an error if the given section does not exist. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:has_option" ><A NAME="v%3Ahas_option" ></A ></A ><B >has_option</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#has_option" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Indicates whether the given option is present. Returns True only if the given section is present AND the given option is present in that section. No special <TT >DEFAULT</TT > processing is done. No exception could be raised or error returned. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:items" ><A NAME="v%3Aitems" ></A ></A ><B >items</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m [(<A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A >, <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A >)]</TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#items" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Returns a list of <TT >(optionname, value)</TT > pairs representing the content of the given section. Returns an error the section is invalid. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="19" ><A NAME="19" >Modifying Data </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:set" ><A NAME="v%3Aset" ></A ></A ><B >set</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#set" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Sets the option to a new value, replacing an existing one if it exists. </P ><P >Returns an error if the section does not exist. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:setshow" ><A NAME="v%3Asetshow" ></A ></A ><B >setshow</B > :: (<A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Text-Show.html#t%3AShow" >Show</A > a, <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m) => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> a -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#setshow" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Sets the option to a new value, replacing an existing one if it exists. It requires only a showable value as its parameter. This can be used with bool values, as well as numeric ones. </P ><P >Returns an error if the section does not exist. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:remove_option" ><A NAME="v%3Aremove_option" ></A ></A ><B >remove_option</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> <A HREF="Data-ConfigFile.html#t%3AOptionSpec" >OptionSpec</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#remove_option" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Removes the specified option. Returns a <TT ><A HREF="Data-ConfigFile.html#v%3ANoSection" >NoSection</A ></TT > error if the section does not exist and a <TT ><A HREF="Data-ConfigFile.html#v%3ANoOption" >NoOption</A ></TT > error if the option does not exist. Otherwise, returns the new <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > object. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:add_section" ><A NAME="v%3Aadd_section" ></A ></A ><B >add_section</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#add_section" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" >Adds the specified section name. Returns a <TT ><A HREF="Data-ConfigFile.html#v%3ASectionAlreadyExists" >SectionAlreadyExists</A ></TT > error if the section was already present. Otherwise, returns the new <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > object. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:remove_section" ><A NAME="v%3Aremove_section" ></A ></A ><B >remove_section</B > :: <A HREF="/usr/share/doc/ghc/html/libraries/mtl-1.1.0.2/Control-Monad-Error-Class.html#t%3AMonadError" >MonadError</A > <A HREF="Data-ConfigFile.html#t%3ACPError" >CPError</A > m => <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3ASectionSpec" >SectionSpec</A > -> m <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#remove_section" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Removes the specified section. Returns a <TT ><A HREF="Data-ConfigFile.html#v%3ANoSection" >NoSection</A ></TT > error if the section does not exist; otherwise, returns the new <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > object. </P ><P >This call may not be used to remove the <TT >DEFAULT</TT > section. Attempting to do so will always cause a <TT ><A HREF="Data-ConfigFile.html#v%3ANoSection" >NoSection</A ></TT > error. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:merge" ><A NAME="v%3Amerge" ></A ></A ><B >merge</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#merge" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Combines two <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT >s into one. </P ><P >Any duplicate options are resolved to contain the value specified in the second parser. </P ><P >The <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > options in the resulting object will be set as they are in the second one passed to this function. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="20" ><A NAME="20" >Output Data </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="topdecl" ><TABLE CLASS="declbar" ><TR ><TD CLASS="declname" ><A NAME="v:to_string" ><A NAME="v%3Ato_string" ></A ></A ><B >to_string</B > :: <A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A > -> <A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Data-Char.html#t%3AString" >String</A ></TD ><TD CLASS="declbut" ><A HREF="src/Data-ConfigFile.html#to_string" >Source</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="doc" ><P >Converts the <TT ><A HREF="Data-ConfigFile.html#t%3AConfigParser" >ConfigParser</A ></TT > to a string representation that could be later re-parsed by this module or modified by a human. </P ><P >Note that this does not necessarily re-create a file that was originally loaded. Things may occur in a different order, comments will be removed, etc. The conversion makes an effort to make the result human-editable, but it does not make an effort to make the result identical to the original input. </P ><P >The result is, however, guaranteed to parse the same as the original input. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="botbar" >Produced by <A HREF="http://www.haskell.org/haddock/" >Haddock</A > version 2.6.1</TD ></TR ></TABLE ></BODY ></HTML >