Data.ConnectionString

Introduction

This module is intended for parsing connection strings in a manner that is consistent with .NET's DbConnectionStringBuilder class.

The syntax of a connection string appears quite simple at first glance, and consists of a list of key-value pairs separated by semicolons:

>>> parse "key=value; key2 = value2"
Right (fromList [("key","value"),("key2","value2")])

However, the format can be more complicated than expected.

Examples

A value may be single-quoted (single quotes can be escaped inside a single-quoted string by doubling them):

>>> parse "squote='value with '' quotes'"
Right (fromList [("squote","value with ' quotes")])

Or double-quoted (double quotes can also be escaped inside a double-quoted string by doubling them):

>>> parse "dquote=\"value with \"\" quotes\""
Right (fromList [("dquote","value with \" quotes")])

Quotes of both kinds may be present in keys:

>>> parse "'quote\"=value"
Right (fromList [("'quote\"","value")])

Whitespace is ignored everywhere except in quoted strings and inside keys or unquoted values:

>>> parse "; a key = v v\t\n;\t key 2 = \"v v\"\n;\t key 3 = 'v v'; "
Right (fromList [("a key","v v"),("key 2","v v"),("key 3","v v")])

Equals signs may be escaped in keys by doubling them:

>>> parse "1==2=false"
Right (fromList [("1=2","false")])

Later values override earlier ones:

>>> parse "key=value;key=value2"
Right (fromList [("key","value2")])

Assigning a key no value will remove it:

>>> parse "key=value;key="
Right (fromList [])

However, you can assign an empty value by giving it a quoted value:

>>> parse "key=value;key=''"
Right (fromList [("key","")])

On the other hand, not providing a key doesn't make any sense:

>>> parse "key=value;=value"
Left "1:11:\nunexpected '='\nexpecting ';', end of input, or white space\n"

>>> parse "=value"
Left "1:1:\nunexpected '='\nexpecting ';', end of input, or white space\n"

This module implements all of these quirks for you!

Documentation

type ConnectionString s = Map s s

A connection string is a set of keys and values.

parse :: Parseable s => s -> Either String (ConnectionString s)

Parses a connection string, or fails with an error.

You can parse String inputs:

>>> parse ("key=value;key2=value2")
Right (fromList [("key","value"),("key2","value2")])

Or you can parse Text inputs:

>>> :set -XOverloadedStrings
>>> import Data.Text
>>> parse ("key=value;key2=value2" :: Text)
Right (fromList [("key","value"),("key2","value2")])

In either case, parse will produce a ConnectionString that has values of the same type as the input.

type Parseable s = (Stream s, Token s ~ Char, IsString s, Ord s)

The constraints on things that parse can handle. (Essentially this means "either String or Text".)

parser :: Parseable s => Parsec Void s [(s, Maybe s)]

A reusable (Text.Megaparsec) parser for connection strings.

A Nothing in the output list indicates that the corresponding key should be deleted from the set.