diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,12 @@ [KaC]: +## 1.0.0.0 (2021-06-03) + +### Non-Breaking + +* Add Cabal support to `Makefile` + ## 0.4.0.0 (2021-03-27) ### Breaking diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ # TTC: Textual Type Classes +[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![GitHub CI](https://github.com/ExtremaIS/ttc-haskell/workflows/CI/badge.svg?branch=main)](https://github.com/ExtremaIS/ttc-haskell/actions) [![Hackage](https://img.shields.io/hackage/v/ttc.svg)](https://hackage.haskell.org/package/ttc) [![Stackage LTS](https://stackage.org/package/ttc/badge/lts)](https://stackage.org/package/ttc) [![Stackage Nightly](https://stackage.org/package/ttc/badge/nightly)](https://stackage.org/nightly/package/ttc) * [Overview](#overview) + * [`Textual`](#textual) * [`Render`](#render) * [`Parse`](#parse) - * [`Textual`](#textual) + * [Constant Validation](#constant-validation) * [Related Work](#related-work) * [Rendering and Parsing](#rendering-and-parsing) - * [Constant Validation](#constant-validation) + * [Validating Constants](#validating-constants) * [String Type Conversion](#string-type-conversion) * [Project](#project) * [Links](#links) @@ -22,16 +24,52 @@ ## Overview TTC, an initialism of _Textual Type Classes_, is a library that provides -`Render` and `Parse` type classes for conversion between data types and -textual data types (strings). Use the `Show` and `Read` type classes for -debugging/development, and use the `Render` and `Parse` type classes for your -own purposes. +[`Render`](#render) and +[`Parse`](#parse) type classes for conversion between data types and textual +data types (strings). Use the `Show` and `Read` type classes for +debugging/development, and use the [`Render`](#render) and +[`Parse`](#parse) type classes for your own purposes. The library also +provides a [`Textual`](#textual) type class for conversion between textual +data types as well as functions for validating constants at compile-time. -The following is a brief overview of the type classes provided by this -library. See the -[API documentation on Hackage](https://hackage.haskell.org/package/ttc#modules) -for details and the [`examples` directory](examples) for usage examples. +This overview includes a brief introduction of the library. The following +resources are also available: +* [API documentation][] is viewable on Hackage. +* A [series of articles][] gives a guided tour of the library. + 1. [Textual Type Class][] + 2. [Render and Parse][] + 3. [Validated Constants][] + 4. [Best Practices][] +* The [examples][] directory in the GitHub repository contains usage examples. + +[API documentation]: +[series of articles]: +[Textual Type Class]: +[Render and Parse]: +[Validated Constants]: +[Best Practices]: +[examples]: + +### `Textual` + +The `Textual` type class is used to convert between the following textual data +types: + +* `String` +* Strict `Text` +* Lazy `Text` +* Strict `ByteString` +* Lazy `ByteString` + +Conversion between any of these types is direct; it is not done through a +fixed textual data type (such as `String` or `Text`). The key feature of this +type class is that it has a single type variable, making it easy to write +functions that accept arguments and/or returns values that may be any of the +supported textual data types. + +For more details, see the [Textual Type Class][] article. + ### `Render` The `Render` type class renders a data type as a [`Textual`](#textual) data @@ -77,6 +115,8 @@ putStrLn $ "user not found: " ++ TTC.render uname ``` +For more details, see the [Render and Parse][] article. + ### `Parse` The `Parse` type class parses a data type from a [`Textual`](#textual) data @@ -116,38 +156,19 @@ Left err -> putStrLn $ "invalid username: " ++ err ``` -It is common to create data types that have "smart constructors" to ensure -that all constructed values are valid. If the `Username` constructor were -exported, it would be possible to create values with arbitrary `Text`, such -as `Username T.empty`, which is not a valid `Username`. Smart constructors -can be inconvenient when constructing constants, however, as neither runtime -error handling nor failure are desired. This library provides Template -Haskell functions that use `Parse` instances to validate such constants at -compile-time. - -### `Textual` - -The `Textual` type class is used to convert between the following textual data -types: +For more details, see the [Render and Parse][] article. -* `String` -* Strict `Text` -* Lazy `Text` -* Strict `ByteString` -* Lazy `ByteString` +### Constant Validation -Conversion between any of these types is direct; it is not done through a -fixed textual data type (such as `String` or `Text`). The key feature of this -type class is that it has a single type variable, making it easy to write -functions that accept arguments and/or returns values that may be any of the -supported textual data types. +TTC provides functions to validate constants at compile-time, using Template +Haskell. For example, a `Username` constant can be defined as follows: -Functions are provided to convert to/from the following other textual data -types: +```haskell +user :: Username +user = $$(TTC.valid "tcard") +``` -* `Text` `Builder` -* `ByteString` `Builder` -* `ShortByteString` +For more details, see the [Validated Constants][] article. ## Related Work @@ -172,7 +193,7 @@ * [Down with Show! Part 2: What's wrong with the Show type class](https://harry.garrood.me/blog/down-with-show-part-2/) * [Down with Show! Part 3: A replacement for Show](https://harry.garrood.me/blog/down-with-show-part-3/) -### Constant Validation +### Validating Constants The [validated-literals](https://hackage.haskell.org/package/validated-literals) diff --git a/src/Data/TTC.hs b/src/Data/TTC.hs --- a/src/Data/TTC.hs +++ b/src/Data/TTC.hs @@ -163,6 +163,9 @@ -- 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: +-- +-- -- @since 0.1.0.0 class Textual t where -- | Convert to a 'String' @@ -412,6 +415,9 @@ -- -- See the @uname@ and @prompt@ example programs in the @examples@ directory. -- +-- For more details, see the following article: +-- +-- -- @since 0.1.0.0 class Render a where render :: Textual t => a -> t @@ -500,6 +506,9 @@ -- -- See the @uname@ and @prompt@ example programs in the @examples@ directory. -- +-- For more details, see the following article: +-- +-- -- @since 0.3.0.0 class Parse a where parse :: (Textual t, Textual e) => t -> Either e a @@ -740,8 +749,8 @@ -- @since 0.3.0.0 maybeParseWithRead :: (Read a, Textual t) - => t -- ^ textual input to parse - -> Maybe a -- ^ error or parsed value + => t -- ^ textual input to parse + -> Maybe a -- ^ parsed value or 'Nothing' if invalid maybeParseWithRead = readMaybe . toS -- | Implement 'ReadS' using 'parseEnum' @@ -793,6 +802,9 @@ -- validation function for a type using a 'Proxy', or use 'untypedValidOf' to -- pass the 'Proxy' when defining constants. Alternatively, use -- 'mkUntypedValidQQ' to define a validation quasi-quoter. +-- +-- For more details, see the following article: +-- -- | Validate a constant at compile-time using a 'Parse' instance -- diff --git a/ttc.cabal b/ttc.cabal --- a/ttc.cabal +++ b/ttc.cabal @@ -1,5 +1,5 @@ name: ttc -version: 0.4.0.0 +version: 1.0.0.0 category: Data, Text synopsis: Textual Type Classes description: