ttc 0.4.0.0 → 1.0.0.0
raw patch · 4 files changed
+81/−42 lines, 4 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
Files
- CHANGELOG.md +6/−0
- README.md +60/−39
- src/Data/TTC.hs +14/−2
- ttc.cabal +1/−1
CHANGELOG.md view
@@ -24,6 +24,12 @@ [KaC]: <https://keepachangelog.com/en/1.0.0/> +## 1.0.0.0 (2021-06-03)++### Non-Breaking++* Add Cabal support to `Makefile`+ ## 0.4.0.0 (2021-03-27) ### Breaking
README.md view
@@ -1,17 +1,19 @@ # TTC: Textual Type Classes +[](https://www.repostatus.org/#active) [](https://github.com/ExtremaIS/ttc-haskell/actions) [](https://hackage.haskell.org/package/ttc) [](https://stackage.org/package/ttc) [](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]: <https://hackage.haskell.org/package/ttc#modules>+[series of articles]: <https://www.extrema.is/articles/ttc-textual-type-classes>+[Textual Type Class]: <https://www.extrema.is/articles/ttc-textual-type-classes/textual-type-class>+[Render and Parse]: <https://www.extrema.is/articles/ttc-textual-type-classes/render-and-parse>+[Validated Constants]: <https://www.extrema.is/articles/ttc-textual-type-classes/validated-constants>+[Best Practices]: <https://www.extrema.is/articles/ttc-textual-type-classes/best-practices>+[examples]: <https://github.com/ExtremaIS/ttc-haskell/tree/main/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)
src/Data/TTC.hs view
@@ -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:+-- <https://www.extrema.is/articles/ttc-textual-type-classes/textual-type-class>+-- -- @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:+-- <https://www.extrema.is/articles/ttc-textual-type-classes/render-and-parse>+-- -- @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:+-- <https://www.extrema.is/articles/ttc-textual-type-classes/render-and-parse>+-- -- @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:+-- <https://www.extrema.is/articles/ttc-textual-type-classes/validated-constants> -- | Validate a constant at compile-time using a 'Parse' instance --
ttc.cabal view
@@ -1,5 +1,5 @@ name: ttc-version: 0.4.0.0+version: 1.0.0.0 category: Data, Text synopsis: Textual Type Classes description: