-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A library for parsing connection strings.
--   
--   Parses connection strings in a manner that agrees with the format that
--   .NET accepts (e.g. ADO.NET).
@package connection-string
@version 0.1.0.0


-- | <h2>Introduction</h2>
--   
--   This module is intended for parsing connection strings in a manner
--   that is consistent with .NET's <a>DbConnectionStringBuilder</a> 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:
--   
--   <pre>
--   &gt;&gt;&gt; parse "key=value; key2 = value2"
--   Right (fromList [("key","value"),("key2","value2")])
--   </pre>
--   
--   However, the format can be more complicated than expected.
--   
--   <h2>Examples</h2>
--   
--   A value may be single-quoted (single quotes can be escaped inside a
--   single-quoted string by doubling them):
--   
--   <pre>
--   &gt;&gt;&gt; parse "squote='value with '' quotes'"
--   Right (fromList [("squote","value with ' quotes")])
--   </pre>
--   
--   Or double-quoted (double quotes can also be escaped inside a
--   double-quoted string by doubling them):
--   
--   <pre>
--   &gt;&gt;&gt; parse "dquote=\"value with \"\" quotes\""
--   Right (fromList [("dquote","value with \" quotes")])
--   </pre>
--   
--   Quotes of both kinds may be present in keys:
--   
--   <pre>
--   &gt;&gt;&gt; parse "'quote\"=value"
--   Right (fromList [("'quote\"","value")])
--   </pre>
--   
--   Whitespace is ignored everywhere except in quoted strings and inside
--   keys or unquoted values:
--   
--   <pre>
--   &gt;&gt;&gt; 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")])
--   </pre>
--   
--   Equals signs may be escaped in keys by doubling them:
--   
--   <pre>
--   &gt;&gt;&gt; parse "1==2=false"
--   Right (fromList [("1=2","false")])
--   </pre>
--   
--   Later values override earlier ones:
--   
--   <pre>
--   &gt;&gt;&gt; parse "key=value;key=value2"
--   Right (fromList [("key","value2")])
--   </pre>
--   
--   Assigning a key no value will remove it:
--   
--   <pre>
--   &gt;&gt;&gt; parse "key=value;key="
--   Right (fromList [])
--   </pre>
--   
--   However, you can assign an empty value by giving it a quoted value:
--   
--   <pre>
--   &gt;&gt;&gt; parse "key=value;key=''"
--   Right (fromList [("key","")])
--   </pre>
--   
--   On the other hand, not providing a key doesn't make any sense:
--   
--   <pre>
--   &gt;&gt;&gt; parse "key=value;=value"
--   Left "1:11:\nunexpected '='\nexpecting ';', end of input, or white space\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parse "=value"
--   Left "1:1:\nunexpected '='\nexpecting ';', end of input, or white space\n"
--   </pre>
--   
--   This module implements all of these quirks for you!
module Data.ConnectionString

-- | A connection string is a set of keys and values.
type ConnectionString s = Map s s

-- | Parses a connection string, or fails with an error.
--   
--   You can parse <a>String</a> inputs:
--   
--   <pre>
--   &gt;&gt;&gt; parse ("key=value;key2=value2")
--   Right (fromList [("key","value"),("key2","value2")])
--   </pre>
--   
--   Or you can parse <a>Text</a> inputs:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; import Data.Text
--   
--   &gt;&gt;&gt; parse ("key=value;key2=value2" :: Text)
--   Right (fromList [("key","value"),("key2","value2")])
--   </pre>
--   
--   In either case, <a>parse</a> will produce a <a>ConnectionString</a>
--   that has values of the same type as the input.
parse :: Parseable s => s -> Either String (ConnectionString s)

-- | The constraints on things that <a>parse</a> can handle. (Essentially
--   this means "either <a>String</a> or <a>Text</a>".)
type Parseable s = (Stream s, Token s ~ Char, IsString s, Ord s)

-- | A reusable (<a>Text.Megaparsec</a>) parser for connection strings.
--   
--   A <a>Nothing</a> in the output list indicates that the corresponding
--   key should be deleted from the set.
parser :: Parseable s => Parsec Void s [(s, Maybe s)]