Data.TTC

TTC, an initialism of Textual Type Classes, is a library that provides type classes for conversion between data types and textual data types (strings).

This library is meant to be imported qualified, as follows:

import qualified Data.TTC as TTC

Textual

class Textual t

The Textual type class is used to convert between the following textual data types:

• String (S)
• Strict Text (T)
• Lazy Text (TL)
• Strict ByteString (BS)
• Lazy ByteString (BSL)

ByteString values are assumed to be UTF-8 encoded text. Invalid bytes are replaced with the Unicode replacement character U+FFFD. In cases where different behavior is required, process ByteString values before using this class.

The key feature of this type class is that it has a single type variable, making it easy to write functions that accepts arguments and/or returns values that may be any of the supported textual data types.

Note that support for additional data types cannot be implemented by writing instances. Adding support for additional data types would require changing the class definition itself. This is the price paid for having only one type variable instead of two.

Minimal complete definition

toS, toT, toTL, toBS, toBSL, convert

Instances

Textual String

Defined in Data.TTC

Methods

toS :: String -> String

toT :: String -> Text

toTL :: String -> Text

toBS :: String -> ByteString

toBSL :: String -> ByteString

convert :: Textual t' => t' -> String

Textual ByteString

Defined in Data.TTC

Methods

toS :: ByteString -> String

toT :: ByteString -> Text

toTL :: ByteString -> Text

toBS :: ByteString -> ByteString0

toBSL :: ByteString -> ByteString

convert :: Textual t' => t' -> ByteString

Textual ByteString

Defined in Data.TTC

Methods

toS :: ByteString -> String

toT :: ByteString -> Text

toTL :: ByteString -> Text

toBS :: ByteString -> ByteString

toBSL :: ByteString -> ByteString0

convert :: Textual t' => t' -> ByteString

Textual Text

Defined in Data.TTC

Methods

toS :: Text -> String

toT :: Text -> Text0

toTL :: Text -> Text

toBS :: Text -> ByteString

toBSL :: Text -> ByteString

convert :: Textual t' => t' -> Text

Textual Text

Defined in Data.TTC

Methods

toS :: Text -> String

toT :: Text -> Text

toTL :: Text -> Text0

toBS :: Text -> ByteString

toBSL :: Text -> ByteString

convert :: Textual t' => t' -> Text

convert :: (Textual t, Textual t') => t' -> t

Convert between any supported textual data types

"To" Conversions

These functions are equivalent to convert, but they specify the type being converted to. Use them to avoid having to write type annotations in cases where the type is ambiguous.

toS :: Textual t => t -> String

Convert to a String

toT :: Textual t => t -> Text

Convert to strict Text

toTL :: Textual t => t -> Text

Convert to lazy Text

toBS :: Textual t => t -> ByteString

Convert to a strict ByteString

toBSL :: Textual t => t -> ByteString

Convert to a lazy ByteString

"From" Conversions

These functions are equivalent to convert, but they specify the type being converted from. Use them to avoid having to write type annotations in cases where the type is ambiguous.

fromS :: Textual t => String -> t

Convert from a String

fromT :: Textual t => Text -> t

Convert from strict Text

fromTL :: Textual t => Text -> t

Convert from lazy Text

fromBS :: Textual t => ByteString -> t

Convert from a strict ByteString

fromBSL :: Textual t => ByteString -> t

Convert from a lazy ByteString

"As" Conversions

These functions are used to convert a Textual argument of a function to a specific type. Use them to reduce boilerplate in small function definitions.

asS :: Textual t => (String -> a) -> t -> a

Convert an argument to a String

asT :: Textual t => (Text -> a) -> t -> a

Convert an argument to strict Text

asTL :: Textual t => (Text -> a) -> t -> a

Convert an argument to lazy Text

asBS :: Textual t => (ByteString -> a) -> t -> a

Convert an argument to a strict ByteString

asBSL :: Textual t => (ByteString -> a) -> t -> a

Convert an argument to a lazy ByteString

Other Conversions

These functions are used to convert to/from the following other textual data types:

• Text Builder (TLB)
• ByteString Builder (BSB)
• ShortByteString (SBS)

toTLB :: Textual t => t -> Builder

Convert to a Text Builder

fromTLB :: Textual t => Builder -> t

Convert from a Text Builder

toBSB :: Textual t => t -> Builder

Convert to a ByteString Builder

fromBSB :: Textual t => Builder -> t

Convert from a ByteString Builder

toSBS :: Textual t => t -> ShortByteString

Convert to a ShortByteString

fromSBS :: Textual t => ShortByteString -> t

Convert from a ShortByteString

Render

class Render a where

The Render type class renders a data type as a textual data type.

There are no default instances for the Render type class, so that all instances can be customized per project when desired. Instances for some basic data types are available in Data.TTC.Instances.

Methods

render :: Textual t => a -> t

Instances

Render Char

Defined in Data.TTC.Instances

Methods

render :: Textual t => Char -> t

Render Double

Defined in Data.TTC.Instances

Methods

render :: Textual t => Double -> t

Render Float

Defined in Data.TTC.Instances

Methods

render :: Textual t => Float -> t

Render Int

Defined in Data.TTC.Instances

Methods

render :: Textual t => Int -> t

Render Int8

Defined in Data.TTC.Instances

Methods

render :: Textual t => Int8 -> t

Render Int16

Defined in Data.TTC.Instances

Methods

render :: Textual t => Int16 -> t

Render Int32

Defined in Data.TTC.Instances

Methods

render :: Textual t => Int32 -> t

Render Int64

Defined in Data.TTC.Instances

Methods

render :: Textual t => Int64 -> t

Render Integer

Defined in Data.TTC.Instances

Methods

render :: Textual t => Integer -> t

Render Word

Defined in Data.TTC.Instances

Methods

render :: Textual t => Word -> t

Render Word8

Defined in Data.TTC.Instances

Methods

render :: Textual t => Word8 -> t

Render Word16

Defined in Data.TTC.Instances

Methods

render :: Textual t => Word16 -> t

Render Word32

Defined in Data.TTC.Instances

Methods

render :: Textual t => Word32 -> t

Render Word64

Defined in Data.TTC.Instances

Methods

render :: Textual t => Word64 -> t

Render String

Defined in Data.TTC.Instances

Methods

render :: Textual t => String -> t

Render ByteString

Defined in Data.TTC.Instances

Methods

render :: Textual t => ByteString -> t

Render ByteString

Defined in Data.TTC.Instances

Methods

render :: Textual t => ByteString -> t

Render Text

Defined in Data.TTC.Instances

Methods

render :: Textual t => Text -> t

Render Text

Defined in Data.TTC.Instances

Methods

render :: Textual t => Text -> t

Rendering Specific Types

These functions are equivalent to render, but they specify the type being rendered to. Use them to avoid having to write type annotations in cases where the type is ambiguous.

renderS :: Render a => a -> String

Render to a String

renderT :: Render a => a -> Text

Render to strict Text

renderTL :: Render a => a -> Text

Render to lazy Text

renderBS :: Render a => a -> ByteString

Render to a strict ByteString

renderBSL :: Render a => a -> ByteString

Render to a lazy ByteString

Render Utilities

renderWithShow :: (Show a, Textual t) => a -> t

Render a value to a textual data type using the Show instance

Parse

class Parse a where

The Parse type class parses a data type from a textual data type.

There are no default instances for the Parse type class, so that all instances can be customized per project when desired. Instances for some basic data types are available in Data.TTC.Instances.

Methods

parse :: Textual t => t -> Either String a

Instances

Parse Char

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Char

Parse Double

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Double

Parse Float

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Float

Parse Int

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Int

Parse Int8

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Int8

Parse Int16

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Int16

Parse Int32

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Int32

Parse Int64

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Int64

Parse Integer

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Integer

Parse Word

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Word

Parse Word8

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Word8

Parse Word16

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Word16

Parse Word32

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Word32

Parse Word64

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Word64

Parse String

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String String

Parse ByteString

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String ByteString

Parse ByteString

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String ByteString

Parse Text

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Text

Parse Text

Defined in Data.TTC.Instances

Methods

parse :: Textual t => t -> Either String Text

Parsing From Specific Types

These functions are equivalent to parse, but they specify the type being parsed from. Use them to avoid having to write type annotations in cases where the type is ambiguous.

parseS :: Parse a => String -> Either String a

Parse from a String

parseT :: Parse a => Text -> Either String a

Parse from strict Text

parseTL :: Parse a => Text -> Either String a

Parse from lazy Text

parseBS :: Parse a => ByteString -> Either String a

Parse from a strict ByteString

parseBSL :: Parse a => ByteString -> Either String a

Parse from a lazy ByteString

Maybe Parsing

The parseMaybe function parses to a Maybe type instead of an Either type. The rest of the functions are equivalent to parseMaybe, but they specify the type being parsed from. Use them to avoid having to write type annotations in cases where the type is ambiguous.

parseMaybe :: Parse a => Textual t => t -> Maybe a

Parse to a Maybe type

parseMaybeS :: Parse a => String -> Maybe a

Parse from a String to a Maybe type

parseMaybeT :: Parse a => Text -> Maybe a

Parse from strict Text to a Maybe type

parseMaybeTL :: Parse a => Text -> Maybe a

Parse from lazy Text to a Maybe type

parseMaybeBS :: Parse a => ByteString -> Maybe a

Parse from a strict ByteString to a Maybe type

parseMaybeBSL :: Parse a => ByteString -> Maybe a

Parse from a lazy ByteString to a Maybe type

Unsafe Parsing

The parseUnsafe function raises an exception on error instead of using an Either type. It should only be used when an error is not possible. The rest of the functions are equivalent to parseUnsafe, but they specify the type being parsed from. Use them to avoid having to write type annotations in cases where the type is ambiguous.

parseUnsafe :: (Parse a, Textual t) => t -> a

Unsafely parse

parseUnsafeS :: Parse a => String -> a

Unsafely parse to a String

parseUnsafeT :: Parse a => Text -> a

Unsafely parse to strict Text

parseUnsafeTL :: Parse a => Text -> a

Unsafely parse to lazy Text

parseUnsafeBS :: Parse a => ByteString -> a

Unsafely parse to a strict ByteString

parseUnsafeBSL :: Parse a => ByteString -> a

Unsafely parse to a lazy ByteString

Parse Utilities

parseEnum

Arguments

:: (Bounded a, Enum a, Render a, Textual t)

=> Bool

case-insensitive when True

-> Bool

accept unique prefixes when True

-> e

invalid input error

-> e

ambiguous input error

-> t

textual input to parse

-> Either e a

error or parsed value

Parse a value in an enumeration

parseEnum'

Arguments

:: (Bounded a, Enum a, Render a, Textual t)

=> String

name to include in error messages

-> Bool

case-insensitive when True

-> Bool

accept unique prefixes when True

-> t

textual input to parse

-> Either String a

error or parsed value

Parse a value in an enumeration, with String error messages

The following English error messages are returned:

• "invalid {name}" when there are no matches
• "ambiguous {name}" when there is more than one match

parseWithRead

Arguments

:: (Read a, Textual t)

=> e

invalid input error

-> t

textual input to parse

-> Either e a

error or parsed value

Parse a value using the Read instance

parseWithRead'

Arguments

:: (Read a, Textual t)

=> String

name to include in error messages

-> t

textual input to parse

-> Either String a

error or parsed value

Parse a value using the Read instance, with String error messages

The following English error message is returned:

• "invalid {name}" when the parse fails

readsEnum

Arguments

:: (Bounded a, Enum a, Render a)

=> Bool

case-insensitive when True

-> Bool

accept unique prefixes when True

-> ReadS a

Implement ReadS using parseEnum

This implementation expects all of the input to be consumed.

readsWithParse :: Parse a => ReadS a

Implement ReadS using a Parse instance

This implementation expects all of the input to be consumed.

valid :: (Parse a, Lift a) => String -> Q (TExp a)

Validate a constant at compile-time using a Parse instance

This function parses the String at compile-time in order to validate it. When valid, the result is compiled in, so the result type must have a Lift instance. Use validOf when this is inconvenient.

validOf :: Parse a => Proxy a -> String -> Q (TExp a)

Validate a constant at compile-time using a Parse instance

This function parses the String at compile-time in order to validate it. When valid, the String is compiled in, to be parsed again at run-time. Since the result is not compiled in, no Lift instance is required.

mkValid :: String -> Name -> DecsQ

Make a valid function using validOf for the given type