| Copyright | (c) Eric Mertens 2017 |
|---|---|
| License | ISC |
| Maintainer | emertens@gmail.com |
| Safe Haskell | Safe |
| Language | Haskell2010 |
Config
Description
This module parses files using the syntax demonstrated below. The full lexical syntax is available in the Alex source file. The full grammar is available in the Happy source file.
Configuration file schemas can be specified using the
config-schema
package. This package helps extract application-specific meaning
from a Value, and can also generate documentation for the supported
format.
The config-value format offers a simple, layout-based syntax for
specifying configuration information. In addition configuration
values can be pretty-printed back into valid concrete syntax.
Example
-- Line comments until newline
layout:
based:
configuration:
{} -- empty section
sections:
"glguy"
{- Block comments
{- nested comments -}
"O'caml style {- strings in comments"
so you can comment out otherwise valid
portions of your config
-}
atoms : yes
decimal : -1234
hexadecimal: 0x1234
octal : 0o1234
binary : 0b1010
lists:
* sections: in-lists
next-section: still-in-list
* [ "inline", "lists" ]
* * "nestable"
* "layout"
* "lists"
* 3
unicode : "standard Haskell format strings (1 ≤ 2)\x2228(2 ≤ 3)"
Syntax
A configuration file should contain a single value at the top-level. Typically this value will be a list of sections (as seen in the example above).
Unicode character classes are fully supported. The alpha and digit character classes use the full Unicode range, rather than merely the ASCII ranges.
There are 5 distinct types of values possible in a configuration file:
- Sections list (list of key-value pairs)
- Lists
- Text
- Numbers
- Atoms
Sections list
KEY: VALUE KEY: VALUE KEY: VALUE
Sections lists are lists of key-value pairs. Each key in the list should start on the same column in the file. The value of the pair should be indented to the right of the key.
The lexical syntax for section names is identical to the lexical syntax of atoms. Section names are nonempty sequences starting with an alpha character followed by zero or more alpha, digit, period (.), underscore (_), or dash (-).
Section lists can be nested.
Section lists can be used inline, without layout, but surrounding them
with { and } and separating the sections with ,. The empty sections
list is specified with {}.
Examples:
key-1 : -- spaces are allowed between the section name and the colon
key-1.1: value-1.1
key-1.2: [ value-1.2 ]
key-2: value-2
key-3: {} -- the value for key-3 is the empty sections list
key-4: { red: 1, blue: 2} -- inline syntax for sublist
List
* VALUE * VALUE * VALUE
Lists can be specified using either layout or inline syntax. There is no distinction between the two syntaxes in the abstract syntax.
Inline lists are surrounded by [ and ] with elements separated by ,. The final
list element may be terminated with a trailing comma.
Example: [1, 2, 3]
Layout list entries are started with a leading *. Each leading * must occur
in the some column of the file. Lists can be nested by starting the new list
on a column to the right of the current list.
Layout based lists can not occur inside inline list syntax. Layout based section lists can occur inside layout based lists
Example:
-- One list element containing an atom * item-1 -- One list element containing a two element list * * item-2.1 * item-2.2 -- One list element containing two key-value pairs * key-1: value-1 key-2: value-2
Text
"quoted string literals"
Text values are specified using the Haskell string literal syntax.
Text values are distinct from atoms described below. This allows
a configuration file to make a distinction between the atom default
and the text value "default", for example.
For a detailed description of Haskell string literal syntax, see Haskell 2010 2.6 Character and String Literals
Number
123.456
Numbers can be written with integer and floating-point literals.
Prefix numbers with - to construct a negative number.
Integer literals support alternate base described below.
Floating-point literals can specify a power-of-10 exponent.
Bases
- No prefix for decimal (base 10) integer literals
- Prefix binary (base 2) integer literals with
0bor0B - Prefix octal (base 8) integer literals with
0oor0O - Prefix hexadecimal (base 16) integer literals with
0xor0X. Upper and lower-cased hex digits are supported.
List of examples:
[ 0, 42, -42, 123.45, 6E7, 1e+10, 3.4e-5, 0xfF, 0b101010, -0o77 ]
Atom
unquoted-string
Atoms are unquoted strings that are distinct from normal text values. This type is intended to represent enumerations in a configuration file.
Atoms are nonempty sequences starting with an alpha character followed by zero or more alpha, digit, period (.), underscore (_), or dash (-).
Lexical syntax: $alpha [$alpha $digit $unidigit \. _ \-]*
List of examples:
[ yes, no, default, MODE-61 ]
Comments
Comments are valid white-space.
An ordinary comment begins with -- and extends to the following newline.
-- This is a comment
Use pairs of {- and -} to create comments that can span multiple
lines. These comments can be nested.
{- this {- is -}
a comment -}
- parse :: Text -> Either ParseError (Value Position)
- data Position = Position {}
- pretty :: Value a -> Doc
- data Section a = Section {
- sectionAnn :: a
- sectionName :: Text
- sectionValue :: Value a
- data Value a
- newtype Atom = MkAtom {}
- valueAnn :: Value a -> a
- data ParseError = ParseError Position String
Parsing
Arguments
| :: Text | source text |
| -> Either ParseError (Value Position) | error message or parsed value |
Parse a configuration file and return the result on the right, or the position of an error on the left.
The resulting value is annotated with source file locations.
Note: Text file lines are terminated by new-lines.
A position in a text file
Pretty-printing
pretty :: Value a -> Doc Source #
Pretty-print a Value as shown in the example.
Sections will nest complex values underneath with
indentation and simple values will be rendered on
the same line as their section.
Types
Constructors
| Section | |
Fields
| |
Instances
| Functor Section Source # | |
| Foldable Section Source # | |
| Traversable Section Source # | |
| Generic1 Section Source # | |
| Eq a => Eq (Section a) Source # | |
| Data a => Data (Section a) Source # | |
| Read a => Read (Section a) Source # | |
| Show a => Show (Section a) Source # | |
| Generic (Section a) Source # | |
| type Rep1 Section Source # | |
| type Rep (Section a) Source # | |
Sum type of the values supported by this language.
The first field of the Number constructor is the based used in the concrete
syntax of the configuration value.
The Floating constructor stores the coefficient and power-of-10 exponent used in
the concrete syntax. This allows representing numbers that would
otherwise overflow a Double.
Value is parameterized over an annotation type indented to be used for
file position or other application specific information.
Examples:
Constructors
| Sections a [Section a] | lists of key-value pairs |
| Number a Int Integer | integer literal base (2, 8, 10, or 16) and integer value |
| Floating a Integer Integer | coef exponent: coef * 10 ^ exponent |
| Text a Text | quoted strings |
| Atom a Atom | unquoted strings |
| List a [Value a] | lists |
Instances
| Functor Value Source # | |
| Foldable Value Source # | |
| Traversable Value Source # | |
| Generic1 Value Source # | |
| Eq a => Eq (Value a) Source # | |
| Data a => Data (Value a) Source # | |
| Read a => Read (Value a) Source # | |
| Show a => Show (Value a) Source # | |
| Generic (Value a) Source # | |
| type Rep1 Value Source # | |
| type Rep (Value a) Source # | |
Errors
data ParseError Source #
Error messages that can occur during parsing annotated with a file position.
Constructors
| ParseError Position String |
Instances
| Eq ParseError Source # | |
| Ord ParseError Source # | |
| Read ParseError Source # | |
| Show ParseError Source # | |
| Exception ParseError Source # |
|