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.

For more details, see the following article: https://www.extrema.is/articles/ttc-textual-type-classes/textual-type-class

Since: 0.1.0.0

Convert between any supported textual data types

Since: 0.1.0.0

Convert to a String

Since: 0.1.0.0

Convert to strict Text

Since: 0.1.0.0

Convert to lazy Text

Since: 0.1.0.0

Convert to a strict ByteString

Since: 0.1.0.0

Convert to a lazy ByteString

Since: 0.1.0.0

Convert from a String

Since: 0.1.0.0

Convert from strict Text

Since: 0.1.0.0

Convert from lazy Text

Since: 0.1.0.0

Convert from a strict ByteString

Since: 0.1.0.0

Convert from a lazy ByteString

Since: 0.1.0.0

Convert an argument to a String

Since: 0.1.0.0

Convert an argument to strict Text

Since: 0.1.0.0

Convert an argument to lazy Text

Since: 0.1.0.0

Convert an argument to a strict ByteString

Since: 0.1.0.0

Convert an argument to a lazy ByteString

Since: 0.1.0.0

Convert to a Text Builder

Since: 0.1.0.0

Convert from a Text Builder

Since: 0.1.0.0

Convert to a ByteString Builder

Since: 0.1.0.0

Convert from a ByteString Builder

Since: 0.1.0.0

Convert to a ShortByteString

Since: 0.1.0.0

Convert from a ShortByteString

Since: 0.1.0.0

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.

See the uname and prompt example programs in the examples directory.

For more details, see the following article: https://www.extrema.is/articles/ttc-textual-type-classes/render-and-parse

Since: 0.1.0.0

Render to a String

Since: 0.1.0.0

Render to strict Text

Since: 0.1.0.0

Render to lazy Text

Since: 0.1.0.0

Render to a strict ByteString

Since: 0.1.0.0

Render to a lazy ByteString

Since: 0.1.0.0

Render to a Text Builder

Since: 0.4.0.0

Render to a ByteString Builder

Since: 0.4.0.0

Render to a ShortByteString

Since: 0.4.0.0

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

Since: 0.1.0.0

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.

See the uname and prompt example programs in the examples directory.

For more details, see the following article: https://www.extrema.is/articles/ttc-textual-type-classes/render-and-parse

Since: 0.3.0.0

Parse from a String

Since: 0.3.0.0

Parse from strict Text

Since: 0.3.0.0

Parse from lazy Text

Since: 0.3.0.0

Parse from a strict ByteString

Since: 0.3.0.0

Parse from a lazy ByteString

Since: 0.3.0.0

Parse to a Maybe type

Since: 0.3.0.0

Parse from a String to a Maybe type

Since: 0.3.0.0

Parse from strict Text to a Maybe type

Since: 0.3.0.0

Parse from lazy Text to a Maybe type

Since: 0.3.0.0

Parse from a strict ByteString to a Maybe type

Since: 0.3.0.0

Parse from a lazy ByteString to a Maybe type

Since: 0.3.0.0

Unsafely parse

Since: 0.1.0.0

Unsafely parse to a String

Since: 0.1.0.0

Unsafely parse to strict Text

Since: 0.1.0.0

Unsafely parse to lazy Text

Since: 0.1.0.0

Unsafely parse to a strict ByteString

Since: 0.1.0.0

Unsafely parse to a lazy ByteString

Since: 0.1.0.0

Parse a value in an enumeration

This function is intended to be used with types that have few choices, as the implementation uses a linear algorithm.

See the enum example program in the examples directory.

Since: 0.1.0.0

Parse a value in an enumeration, with Textual 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

Since: 0.4.0.0

Parse a value using the Read instance

Since: 0.1.0.0

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

The following English error message is returned:

• "invalid {name}" when the parse fails

Since: 0.3.0.0

Parse a value to a Maybe type using the Read instance

Since: 0.3.0.0

Implement ReadS using parseEnum

This implementation expects all of the input to be consumed.

Since: 0.1.0.0

Implement ReadS using a Parse instance

This implementation expects all of the input to be consumed.

Since: 0.3.0.0

Validate a constant at compile-time using a Parse instance

This function parses the String at compile-time and fails compilation on error. When valid, the result is compiled in, so the result type must have a Lift instance. When this is inconvenient, use one of the alternative functions in this library.

This function uses a Template Haskell typed expression. Typed expressions were not supported in haskell-src-exts <1.22.0, which causes problems with old versions of hlint. If the issue affects you, use hlint -i "Parse error" to ignore parse errors or use one of the alternative functions in this library.

Note that the typed Template Haskell API changed in GHC 9. The type displayed in this documentation is determined by the version of GHC used to build the documentation.

The type of this function in GHC 9 or later is as follows:

valid
  :: (MonadFail m, THS.Quote m, Parse a, THS.Lift a)
  => String
  -> THS.Code m a

The type of this function in previous versions of GHC is as follows:

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

This function is used the same way in all GHC versions. See the valid, invalid, and lift example programs in the examples directory. The following is example usage from the valid example:

sample :: Username
sample = $$(TTC.valid "tcard")

Since: 0.1.0.0

Validate a constant at compile-time using a Parse instance

This function requires a Proxy of the result type. Use mkValid to avoid having to pass a Proxy during constant definition.

This function parses the String at compile-time and fails compilation on error. 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.

This function uses a Template Haskell typed expression. Typed expressions were not supported in haskell-src-exts <1.22.0, which causes problems with old versions of hlint. If the issue affects you, use hlint -i "Parse error" to ignore parse errors or use untypedValidOf instead.

Note that the typed Template Haskell API changed in GHC 9. The type displayed in this documentation is determined by the version of GHC used to build the documentation.

The type of this function in GHC 9 or later is as follows:

validOf
  :: (MonadFail m, THS.Quote m, Parse a)
  => Proxy a
  -> String
  -> THS.Code m a

The type of this function in previous versions of GHC is as follows:

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

This function is used the same way in all GHC versions. See the validof example program in the examples directory. The following is example usage from the validof example:

sample :: Username
sample = $$(TTC.validOf (Proxy :: Proxy Username) "tcard")

Since: 0.1.0.0

Make a valid function using validOf for the given type

Create a valid function for a type in order to avoid having to write a Proxy when defining constants.

This function uses a Template Haskell typed expression. Typed expressions were not supported in haskell-src-exts <1.22.0, which causes problems with old versions of hlint. If the issue affects you, use hlint -i "Parse error" to ignore parse errors or use mkUntypedValid instead.

Note that the typed Template Haskell API changed in GHC 9. The type displayed in this documentation is determined by the version of GHC used to build the documentation.

The type of the created valid function in GHC 9 or later is as follows:

$funName
  :: forall m. (MonadFail m, THS.Quote m)
  => String
  -> THS.Code m $resultType

The type of the created valid function in previous versions of GHC is as follows:

$funName
  :: String
  -> TH.Q (TH.TExp $resultType)

This function is used the same way in all GHC versions. See the mkvalid example program in the examples directory. The following is example usage from the mkvalid example:

$(TTC.mkValid "valid" ''Username)

The created valid function can then be used as follows:

sample :: Username
sample = $$(Username.valid "tcard")

Since: 0.1.0.0

Validate a constant at compile-time using a Parse instance

This function requires a Proxy of the result type. Use mkUntypedValid to avoid having to pass a Proxy during constant definition.

This function parses the String at compile-time and fails compilation on error. 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.

See the uvalidof example program in the examples directory. The following is example usage from the uvalidof example:

sample :: Username
sample = $(TTC.untypedValidOf (Proxy :: Proxy Username) "tcard")

Since: 0.2.0.0

Make a valid function using untypedValidOf for the given type

Create a valid function for a type in order to avoid having to write a Proxy when defining constants.

See the mkuvalid example program in the examples directory. The following is example usage from the mkuvalid example:

$(TTC.mkUntypedValid "valid" ''Username)

The created valid function can then be used as follows:

sample :: Username
sample = $(Username.valid "tcard")

Since: 0.2.0.0

Make a valid quasi-quoter using untypedValidOf for the given type

See the uvalidqq example program in the examples directory. The following is example usage from the uvalidqq example:

$(TTC.mkUntypedValidQQ "valid" ''Username)

The created valid function can then be used as follows:

sample :: Username
sample = [Username.valid|tcard|]

Since: 0.2.0.0