-- 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
--   
--   <pre>
--   data Solo a = MkSolo a
--   </pre>
--   
--   Note: it's not a <tt>newtype</tt>
--   
--   <tt>Solo</tt> is available in <tt>base-4.16</tt> (GHC-9.2).
@package OneTuple
@version 0.4.2


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

-- | <tt>Solo</tt> is the canonical lifted 1-tuple, just like <tt>(,)</tt>
--   is the canonical lifted 2-tuple (pair) and <tt>(,,)</tt> is the
--   canonical lifted 3-tuple (triple).
--   
--   The most important feature of <tt>Solo</tt> 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:
--   
--   <pre>
--   index :: Array a -&gt; Int -&gt; a
--   </pre>
--   
--   Now imagine that someone wants to extract a value from an array and
--   store it in a lazy-valued finite map/dictionary:
--   
--   <pre>
--   insert "hello" (arr <tt>index</tt> 12) m
--   </pre>
--   
--   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 <tt>Applicative</tt> context:
--   
--   <pre>
--   indexA :: Applicative f =&gt; Array a -&gt; Int -&gt; f a
--   </pre>
--   
--   When using <tt>indexA</tt> in a <i>pure</i> context, <tt>Solo</tt>
--   serves as a handy <tt>Applicative</tt> functor to hold the result. You
--   could write a non-leaky version of the above example thus:
--   
--   <pre>
--   case arr <tt>indexA</tt> 12 of
--     Solo a -&gt; insert "hello" a m
--   </pre>
--   
--   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
getSolo :: Solo a -> a


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

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


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