lens-5.3.3: Lenses, Folds and Traversals

Safe Haskell | Safe-Inferred
Language | Haskell2010

Control.Lens.Internal.Doctest

Description

This module exists for the sole purpose of redefining the `head` and `tail` functions (which are normally provided by the `Prelude`) so that they can be used in the doctests of `Lens`.

The `head` and `tail` functions are partial, and as of GHC 9.8, there is a `-Wx-partial` warning (implied by `-Wall`) that triggers any time you use either of these functions. This is a fairly reasonable default in most settings, but there are a handful of doctests in `Lens` that do in fact rely on `head` and `tail` being partial functions. These doctests demonstrate that various functions in `Lens` can recover from exceptions that are thrown due to partiality (see, for instance, the `upon` function).

One possible workaround would be to disable `-Wx-partial`. We don't want to disable the warning for all code in `lens`, however—we only want to disable it for a particular group of doctests. It is rather tricky to achieve this level of granularity, unfortunately. This is because tools like `cabal-docspec` rely on GHCi to work, and the statefulness of GHCi's `:set` command means that disabling `-Wx-partial` might leak into other modules' doctests, which we don't want.

Instead, we opt to redefine our own versions of `head` and `tail` here, which do not trigger any `-Wx-partial` warnings, and use them in the `Lens` doctests. This has no impact on anyone reading the doctests, as these functions will look indistinguishable from the `head` and `tail` functions in the `Prelude`. One consequence of this design is that we must export the `Doctest` module, as GHCi (and therefore `cabal-docspec`) won't be able to import it otherwise. Despite this technical oddity, this module should be thought of as internal to `lens`.

# Documentation

head :: [a] -> a #

tail :: [a] -> [a] #