validated-literals: Compile-time checking for partial smart-constructors

[ bsd3, data, library ] [ Propose Tags ] [ Report a vulnerability ]

To disallow invalid input it is common to define (new)types with hidden data constructors. Forcing the user to go through a smart-constructor that enforces invariants and returns Maybe ResultType, preventing the construction of data with invalid values.

However, it is also common to want to include literal values of such types in source text. Things of textual literals for HTML, HTTP, etc. In such cases smart-constructors force us to handle potential conversion failures at runtime, or abusing functions like fromJust to break away all the safety smart-constructors provide. All this despite the fact that we can statically know at compile time that the conversion will always succeed or always fails.

This package provides a typeclasses for using TH to validate the correctness of provided literals at compile. This lets you define, e.g., newtype Even = Even Integer and write:

x :: Even
x = $$(valid 38)

This will check, at compile time, that the provided Integer is, in fact, even and unwrap it from Maybe, avoiding the runtime check.


[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0, 0.2.0, 0.2.0.1, 0.3.0, 0.3.1 (info)
Change log CHANGELOG.md
Dependencies base (>=4.9 && <4.19), template-haskell (>=2.11 && <2.21), th-compat (>=0.1.3 && <0.2) [details]
Tested with ghc ==8.0.2, ghc ==8.2.2, ghc ==8.4.4, ghc ==8.6.5, ghc ==8.8.4, ghc ==8.10.7, ghc ==9.0.2, ghc ==9.2.7, ghc ==9.4.4, ghc ==9.6.2
License BSD-3-Clause
Copyright Copyright © 2015-2021 Merijn Verstraaten
Author Merijn Verstraaten
Maintainer Merijn Verstraaten <merijn@inconsistent.nl>
Revised Revision 3 made by MerijnVerstraaten at 2023-07-13T09:07:51Z
Category Data
Home page https://github.com/merijn/validated-literals
Bug tracker https://github.com/merijn/validated-literals/issues
Source repo head: git clone git+ssh://github.com:merijn/validated-literals
Uploaded by MerijnVerstraaten at 2021-12-02T13:09:26Z
Distributions NixOS:0.3.1
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 2447 total (34 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for validated-literals-0.3.1

[back to package description]

validated-literals: Compile-time checking for partial smart-constructors

BSD3 Hackage hackage-ci Build Status

To disallow invalid input it is common to define (new)types with hidden data constructors. Forcing the user to go through a smart-constructor that enforces invariants and returns Maybe ResultType, preventing the construction of data with invalid values.

However, it is also common to want to include literal values of such types in source text. Things of textual literals for HTML, HTTP, etc. In such cases smart-constructors force us to handle potential conversion failures at runtime, or abusing functions like fromJust to break away all the safety smart-constructors provide. All this despite the fact that we can statically know at compile time that the conversion will always succeed or always fails.

This package provides a typeclasses for using TH to validate the correctness of provided literals at compile. This lets you define, e.g., newtype Even = Even Integer and write:

x :: Even
x = $$(valid 38)

This will check, at compile time, that the provided Integer is, in fact, even and unwrap it from Maybe, avoiding the runtime check.