content: -- | 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 'Data.Data.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 'Data.Data.Lens' that do in
  -- fact rely on 'head' and 'tail' being partial functions. These doctests
  -- demonstrate that various functions in 'Data.Data.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
  -- 'Data.Data.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 'Control.Lens.Internal.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@.
  module Control.Lens.Internal.Doctest
    ( head
    , tail
    ) where
  
  import Prelude hiding (head, tail)
  
  head :: [a] -> a
  head (x:_) = x
  head []    = error "head: empty list"
  
  tail :: [a] -> [a]
  tail (_:xs) = xs
  tail []     = error "tail: empty list"
  