-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Singleton Tuple
--   
--   This package is a compatibility package for a singleton data type
--   
--   
--   data Solo a = MkSolo a
--   
--   
--   Note: it's not a newtype
--   
--   Solo is available in base-4.16 (GHC-9.2).
@package OneTuple
@version 0.4.2

-- | Solo fills the tuple gap with a singleton tuple.
--   
--   Solo does not support the usual parenthesized tuple
--   syntax.
--   
--   Solo
--   
--   
--   
- has the expected laziness properties
--   
- can be pattern-matched
--   
- ships with instances for several standard type classes, including
--   all those supported by H98-standard tuples
--   
- requires no language extensions, except for hierarchical
--   modules
--   
--   
--   Note: on GHC-9.0 getSolo is not a record selector.
module Data.Tuple.Solo

-- | Solo is the canonical lifted 1-tuple, just like (,) is
--   the canonical lifted 2-tuple (pair) and (,,) is the canonical
--   lifted 3-tuple (triple).
--   
--   The most important feature of Solo is that it is possible to
--   force its "outside" (usually by pattern matching) without forcing its
--   "inside", because it is defined as a datatype rather than a newtype.
--   One situation where this can be useful is when writing a function to
--   extract a value from a data structure. Suppose you write an
--   implementation of arrays and offer only this function to index into
--   them:
--   
--   
--   index :: Array a -> Int -> a
--   
--   
--   Now imagine that someone wants to extract a value from an array and
--   store it in a lazy-valued finite map/dictionary:
--   
--   
--   insert "hello" (arr index 12) m
--   
--   
--   This can actually lead to a space leak. The value is not actually
--   extracted from the array until that value (now buried in a map) is
--   forced. That means the entire array may be kept live by just that
--   value! Often, the solution is to use a strict map, or to force the
--   value before storing it, but for some purposes that's undesirable.
--   
--   One common solution is to include an indexing function that can
--   produce its result in an arbitrary Applicative context:
--   
--   
--   indexA :: Applicative f => Array a -> Int -> f a
--   
--   
--   When using indexA in a pure context, Solo
--   serves as a handy Applicative functor to hold the result. You
--   could write a non-leaky version of the above example thus:
--   
--   
--   case arr indexA 12 of
--     Solo a -> insert "hello" a m
--   
--   
--   While such simple extraction functions are the most common uses for
--   unary tuples, they can also be useful for fine-grained control of
--   strict-spined data structure traversals, and for unifying the
--   implementations of lazy and strict mapping functions.
data Solo a
MkSolo :: a -> Solo a
pattern Solo :: a -> Solo a

-- | Extract the value from a Solo. Very often, values should be
--   extracted directly using pattern matching, to control just what gets
--   evaluated when. getSolo is for convenience in situations
--   where that is not the case:
--   
--   When the result is passed to a strict function, it makes no
--   difference whether the pattern matching is done on the "outside" or on
--   the "inside":
--   
--   
--   Data.Set.insert (getSolo sol) set === case sol of Solo v -> Data.Set.insert v set
--   
--   
--   A traversal may be performed in Solo in order to control
--   evaluation internally, while using getSolo to extract the
--   final result. A strict mapping function, for example, could be defined
--   
--   
--   map' :: Traversable t => (a -> b) -> t a -> t b
--   map' f = getSolo . traverse ((Solo $!) . f)
--   
getSolo :: Solo a -> a

-- | This is a module to help migration from OneTuple to
--   Solo. Migrate to use Data.Tuple from
--   base-4.16 or Data.Tuple.Solo with all GHCs.
--   
--   The pattern synonym is provided for GHCs supporting pattern synonyms
--   (7.8+)

-- | Deprecated: Use Data.Tuple.Solo
module Data.Tuple.OneTuple
type OneTuple = Solo
pattern OneTuple :: a -> Solo a
only :: OneTuple a -> a

-- | This module provides TH helpers, which use Solo from this
--   package, for 1-tuples.
module Data.Tuple.Solo.TH
tupE :: Quote m => [m Exp] -> m Exp
