Convert from one textual data type to another

The following textual data types are supported:

• String (S)
• Strict Text (T)
• Lazy Text (TL)
• Text Builder (TLB)
• ShortText (ST)
• Strict ByteString (BS)
• Lazy ByteString (BSL)
• ByteString Builder (BSB)
• ShortByteString (SBS)

Note that support for additional textual data types cannot be implemented by writing instances. Adding support for additional textual data types requires changing the class definition itself. If you need support for additional textual data types, consider using the ETTC library instead.

Encoded values are assumed to be valid UTF-8 encoded text. Conversions must be pure, and any invalid bytes must be replaced with the Unicode replacement character U+FFFD. In cases where different behavior is required, process encoded values separately.

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 from one textual data type to another

The order of the type arguments was changed in version 1.5.0.0.

Since: 0.1.0.0

Convert from a textual data type to a String

Since: 0.1.0.0

Convert from a textual data type to strict Text

Since: 0.1.0.0

Convert from a textual data type to lazy Text

Since: 0.1.0.0

Convert from a textual data type to a Text Builder

Since: 1.1.0.0

Convert from a textual data type to ShortText

Since: 1.4.0.0

Convert from a textual data type to a strict ByteString

Since: 0.1.0.0

Convert from a textual data type to a lazy ByteString

Since: 0.1.0.0

Convert from a textual data type to a ByteString Builder

Since: 1.1.0.0

Convert from a textual data type to a ShortByteString

Since: 1.1.0.0

Convert from a String to a textual data type

Since: 0.1.0.0

Convert from strict Text to a textual data type

Since: 0.1.0.0

Convert from lazy Text to a textual data type

Since: 0.1.0.0

Convert from a Text Builder to a textual data type

Since: 1.1.0.0

Convert from a ShortText to a textual data type

Since: 1.4.0.0

Convert from a strict ByteString to a textual data type

Since: 0.1.0.0

Convert from a lazy ByteString to a textual data type

Since: 0.1.0.0

Convert from a ByteString Builder to a textual data type

Since: 1.1.0.0

Convert from a ShortByteString to a textual data type

Since: 1.1.0.0

Convert a textual data type argument to a String

Since: 0.1.0.0

Convert a textual data type argument to strict Text

Since: 0.1.0.0

Convert a textual data type argument to lazy Text

Since: 0.1.0.0

Convert a textual data type argument to a Text Builder

Since: 1.1.0.0

Convert a textual data type argument to a ShortText

Since: 1.4.0.0

Convert a textual data type argument to a strict ByteString

Since: 0.1.0.0

Convert a textual data type argument to a lazy ByteString

Since: 0.1.0.0

Convert a textual data type argument to a ByteString Builder

Since: 1.1.0.0

Convert a textual data type argument to a ShortByteString

Since: 1.1.0.0

Render a data type as a textual data type

Use Render in your business logic, and only use Show for debugging, as use of Show instances in business logic is a common source of bugs.

When defining an instance, render to the textual data type that is most natural for the data type, and then use convert to handle the conversion to any textual data type. This is particularly wrappers around a textual data type. Example:

newtype Username = Username { usernameText :: Text }

instance TTC.Render Username where
  render = TTC.convert . usernameText

To use render in a context where the types are ambiguous, use the TypeApplications GHC extension to specify one or both types. Example:

-- Render to Text
render _ Text foo

Alternatively, use one of the functions that render to a specific textual data type (such as renderS). Using these functions may make code easier to understand even in cases where the types are not ambiguous.

See the uname and prompt example programs in the ttc-examples directory of the source repository.

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

Since a type may have at most one instance of a given type class, special care must be taken when defining type class instances in a shared library. In particular, orphan instances should generally not be used in shared libraries since they prevent users of the libraries from writing their own instances. Use newtype wrappers instead.

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 defined for the RenderDefault type class, however, and the Template Haskell functions documented below can be used to load these definitions with minimal boilerplate.

Since: 0.1.0.0

Default Render instances for some common types

• The Bool instance renders using the Show instance. This instance was added in version 1.5.0.0.
• The Char instance renders a single-character string.
• Numeric type instances all render using the Show instance.
• Textual data type instances all convert to the target textual data type.

Since: 1.1.0.0

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

To use this function in a context where the types are ambiguous, use the TypeApplications GHC extension to specify one or both types. Example:

-- Render to Text
renderWithShow @Text foo

See the enum example program in the ttc-examples directory of the source repository.

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 Text Builder

Since: 0.4.0.0

Render to a ShortText

Since: 1.4.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 ByteString Builder

Since: 0.4.0.0

Render to a ShortByteString

Since: 0.4.0.0

Parse a data type from a textual data type

Unlike Read, Parse allows you to specify meaningful error messages.

When defining an instance, first convert the textual data type to the textual data type that is most natural for the data type. The as functions (such as asS) provide a convenient way to do this. Note that error is also a textual data type. The withError and prefixError functions can be used to reduce boilerplate. Example:

newtype Username = Username { usernameText :: Text }

instance TTC.Parse Username where
  parse = TTC.asT $ t -> TTC.prefixErrorS "invalid username: " $ do
    unless (T.all isAsciiLower t) $ Left "not only lowercase ASCII letters"
    let len = T.length t
    when (len < 3) $ Left "fewer than 3 characters"
    when (len > 12) $ Left "more than 12 characters"
    pure $ Username t

To use parse in a context where the types are ambiguous, use the TypeApplications GHC extension to specify one or more types. Example:

-- Parse from Text
parse _ Text foo

-- Parse using String errors
parse _ _ String foo

-- Parse from Text using String errors
parse _ Text String foo

Alternatively, use one of the functions that parse from a specific textual data type (such as renderS). Using these functions may make code easier to understand even in cases where the types are not ambiguous.

See the uname and prompt example programs in the ttc-examples directory of the source repository.

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

Since a type may have at most one instance of a given type class, special care must be taken when defining type class instances in a shared library. In particular, orphan instances should generally not be used in shared libraries since they prevent users of the libraries from writing their own instances. Use newtype wrappers instead.

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 defined for the ParseDefault type class, however, and the Template Haskell functions documented below can be used to load these definitions with minimal boilerplate.

Since: 0.3.0.0

The ParseDefault type class provides some default Parse instances.

• The Bool instance parses using the Read instance. This instance was added in version 1.5.0.0.
• The Char instance parses single-character strings.
• Numeric type instances all parse using the Read instance.
• Textual data type instances all convert from the source textual data type.

Since: 1.1.0.0

Create a Parse result from a Textual error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a String error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a Text error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a Text error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a Builder error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a ShortText error message and a Maybe value

Since: 1.4.0.0

Create a Parse result from a ByteString error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a ByteString error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a Builder error message and a Maybe value

Since: 1.2.0.0

Create a Parse result from a ShortByteString error message and a Maybe value

Since: 1.2.0.0

Add a prefix to Textual error messages of a Parse result

Since: 1.2.0.0

Add a prefix to String error messages of a Parse result

Since: 1.2.0.0

Add a prefix to Text error messages of a Parse result

Since: 1.2.0.0

Add a prefix to Text error messages of a Parse result

Since: 1.2.0.0

Add a prefix to Builder error messages of a Parse result

Since: 1.2.0.0

Add a prefix to ShortText error messages of a Parse result

Since: 1.4.0.0

Add a prefix to ByteString error messages of a Parse result

Since: 1.2.0.0

Add a prefix to ByteString error messages of a Parse result

Since: 1.2.0.0

Add a prefix to Builder error messages of a Parse result

Since: 1.2.0.0

Add a prefix to ShortByteString error messages of a Parse result

Since: 1.2.0.0

Parse a value using a Read instance

Since: 0.1.0.0

Parse a value using a Read instance with default 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 result using a Read instance

Since: 0.3.0.0

Parse a value in an enumeration

The Render instance determines the textual values to parse from.

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 ttc-examples directory of the source repository.

Since: 0.1.0.0

Parse a value in an enumeration using default error messages

The Render instance determines the textual values to parse from.

The following English error messages are returned:

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

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

Since: 0.4.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 Text Builder

Since: 1.1.0.0

Parse from a ShortText

Since: 1.4.0.0

Parse from a strict ByteString

Since: 0.3.0.0

Parse from a lazy ByteString

Since: 0.3.0.0

Parse from a ByteString Builder

Since: 1.1.0.0

Parse from a ShortByteString

Since: 1.1.0.0

Parse to a Maybe result

Since: 0.3.0.0

Parse from a String to a Maybe result

Since: 0.3.0.0

Parse from strict Text to a Maybe result

Since: 0.3.0.0

Parse from lazy Text to a Maybe result

Since: 0.3.0.0

Parse from a Text Builder to a Maybe result

Since: 1.1.0.0

Parse from a ShortText to a Maybe result

Since: 1.4.0.0

Parse from a strict ByteString to a Maybe result

Since: 0.3.0.0

Parse from a lazy ByteString to a Maybe result

Since: 0.3.0.0

Parse from a ByteString Builder to a Maybe result

Since: 1.1.0.0

Parse from a ShortByteString to a Maybe result

Since: 1.1.0.0

Parse or fail using MonadFail

Since: 1.3.0.0

Parse from a String or fail using MonadFail

Since: 1.3.0.0

Parse from strict Text or fail using MonadFail

Since: 1.3.0.0

Parse from lazy Text or fail using MonadFail

Since: 1.3.0.0

Parse from a Text Builder or fail using MonadFail

Since: 1.3.0.0

Parse from a ShortText or fail using MonadFail

Since: 1.4.0.0

Parse from a strict ByteString or fail using MonadFail

Since: 1.3.0.0

Parse from a lazy ByteString or fail using MonadFail

Since: 1.3.0.0

Parse from a ByteString Builder or fail using MonadFail

Since: 1.3.0.0

Parse from a ShortByteString or fail using MonadFail

Since: 1.3.0.0

Parse or raise an exception

Since: 0.1.0.0

Parse from a String or raise an exception

Since: 0.1.0.0

Parse from strict Text or raise an exception

Since: 0.1.0.0

Parse from lazy Text or raise an exception

Since: 0.1.0.0

Parse from a Text Builder or raise an exception

Since: 1.1.0.0

Parse from a ShortText or raise an exception

Since: 1.4.0.0

Parse from a strict ByteString or raise an exception

Since: 0.1.0.0

Parse from a lazy ByteString or raise an exception

Since: 0.1.0.0

Parse from a ByteString Builder or raise an exception

Since: 1.1.0.0

Parse from a ShortByteString or raise an exception

Since: 1.1.0.0

Implement ReadS using a Parse instance

This implementation expects all of the input to be consumed.

Since: 0.3.0.0

Implement ReadS using parseEnum

This implementation expects all of the input to be consumed.

Since: 0.1.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 and invalid example programs in the ttc-examples directory of the source repository. 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 ttc-examples directory of the source repository. 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 ttc-examples directory of the source repository. 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 ttc-examples directory of the source repository. 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 ttc-examples directory of the source repository. 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 mkuvalidqq example program in the ttc-examples directory of the source repository. The following is example usage from the mkuvalidqq 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

Load the default Render instance for a type

Example:

TTC.defaultRenderInstance ''Int

Since: 1.5.0.0

Load the default Render instances for any number of types

Example:

TTC.defaultRenderInstances [''Int, ''Int8, ''Int16, ''Int32, ''Int64]

Since: 1.5.0.0

Load the default Parse instance for a type

Example:

TTC.defaultParseInstance ''Int

Since: 1.5.0.0

Load the default Parse instances for any number of types

Example:

TTC.defaultParseInstances [''Int, ''Int8, ''Int16, ''Int32, ''Int64]

Since: 1.5.0.0

Load the default Render and Parse instance for a type

Example:

TTC.defaultRenderAndParseInstance ''Int

Since: 1.5.0.0

Load the default Render and Parse instances for any number of types

Example:

TTC.defaultRenderAndParseInstances
  [''Int, ''Int8, ''Int16, ''Int32, ''Int64]

Since: 1.5.0.0