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


-- | GHC plugin to do inspection esting
--   
--   Some carefully crafted libraries make promises to their users beyond
--   functionality and performance.
--   
--   Examples are: Fusion libraries promise intermediate data structures to
--   be eliminated. Generic programming libraries promise that the generic
--   implementation is identical to the hand-written one. Some libraries
--   may promise allocation-free or branch-free code.
--   
--   Conventionally, the modus operandi in all these cases is that the
--   library author manually inspects the (intermediate or final) code
--   produced by the compiler. This is not only tedious, but makes it very
--   likely that some change, either in the library itself or the
--   surrounding eco-system, breaks the library’s promised without anyone
--   noticing.
--   
--   This package provides a disciplined way of specifying such properties,
--   and have them checked by the compiler. This way, this checking can be
--   part of the ususal development cycle and regressions caught early.
--   
--   See the documentation in <a>Test.Inspection</a> or the project webpage
--   for more examples and more information.
@package inspection-testing
@version 0.1


module Test.Inspection.Internal

-- | An annotation to keep names alive
data KeepAlive
KeepAlive :: KeepAlive
instance Data.Data.Data Test.Inspection.Internal.KeepAlive


-- | This module implements some of analyses of Core expressions necessary
--   for <a>Test.Inspection</a>. Normally, users of this pacakge can ignore
--   this module.
module Test.Inspection.Core

-- | Selects those bindings that define the given variable
slice :: [(Var, CoreExpr)] -> Var -> [(Var, CoreExpr)]

-- | This is a heuristic, which only works if both slices have auxillary
--   variables in the right order. (This is mostly to work-around the buggy
--   CSE in GHC-8.0) It also breaks if there is shadowing.
eqSlice :: [(Var, CoreExpr)] -> [(Var, CoreExpr)] -> Bool

-- | Returns <tt>True</tt> if the given core expression mentions no type
--   constructor anywhere that has the given name.
freeOfType :: [(Var, CoreExpr)] -> Name -> Maybe (Var, CoreExpr)

-- | True if the given variable binding does not allocate, if called fully
--   satisfied.
--   
--   It currently does not look through function calls, which of course
--   could allocate. It should probably at least look through local
--   function calls.
--   
--   The variable is important to know the arity of the function.
doesNotAllocate :: [(Var, CoreExpr)] -> Maybe (Var, CoreExpr)


-- | This module supports the accompanying GHC plugin
--   <a>Test.Inspection.Plugin</a> and adds to GHC the ability to do
--   inspeciton testing.
module Test.Inspection

-- | As seen in the example above, the entry point to inspection testing is
--   the <a>inspect</a> function, to which you pass an <a>Obligation</a>.
inspect :: Obligation -> Q [Dec]

-- | This data type describes an inspection testing obligation.
--   
--   It is recommended to build it using <a>mkObligation</a>, for backwards
--   compatibility when new fields are added. You can also use the more
--   memonic convenience functions like '(===)' or <a>hasNoType</a>.
--   
--   The obligation needs to be passed to <a>inspect</a>.
data Obligation
Obligation :: Name -> Property -> Maybe String -> Bool -> Maybe Loc -> Obligation

-- | The target of a test obligation; invariably the name of a local
--   definition. To get the name of a function <tt>foo</tt>, write
--   <tt>'foo</tt>. This requires <tt>{-# LANGAUGE TemplateHaskell
--   #-}</tt>.
[target] :: Obligation -> Name

-- | The property of the target to be checked.
[property] :: Obligation -> Property

-- | An optional name for the test
[testName] :: Obligation -> Maybe String

-- | Do we expect this property to fail?
[expectFail] :: Obligation -> Bool

-- | The source location where this obligation is defined. This is filled
--   in by <a>inspect</a>.
[srcLoc] :: Obligation -> Maybe Loc

-- | Creates an inspection obligation for the given function name with
--   default values for the optional fields.
mkObligation :: Name -> Property -> Obligation

-- | Properties of the obligation target to be checked.
data Property

-- | Are the two functions equal?
--   
--   More precisely: <tt>f</tt> is equal to <tt>g</tt> if either the
--   definition of <tt>f</tt> is <tt>f = g</tt>, or the definition of
--   <tt>g</tt> is <tt>g = f</tt>, or if the definitions are <tt>f = e</tt>
--   and <tt>g = e</tt>.
EqualTo :: Name -> Property

-- | Does this type not occur anywhere in the definition of the function
--   (neither locally bound nor passed as arguments)
NoType :: Name -> Property

-- | Does this function perform no heap allocations.
NoAllocation :: Property

-- | Convenience function to declare two functions to be equal
(===) :: Name -> Name -> Obligation
infix 1 ===

-- | Convenience function to declare two functions to be equal, but expect
--   the test to fail (This is useful for documentation purposes, or as a
--   TODO list.)
(=/=) :: Name -> Name -> Obligation
infix 1 =/=

-- | Convenience function to declare that a function’s implementation does
--   not mention a type
--   
--   <pre>
--   inspect $ fusedFunction <a>hasNoType</a> ''[]
--   </pre>
hasNoType :: Name -> Name -> Obligation
instance Data.Data.Data Test.Inspection.Obligation
instance Data.Data.Data Test.Inspection.Property


-- | See <a>Test.Inspection</a>.
module Test.Inspection.Plugin

-- | The plugin. It supports the option
--   <tt>-fplugin-opt=Test.Inspection.Plugin=keep-going</tt> to ignore a
--   failing build.
plugin :: Plugin
instance GHC.Classes.Eq Test.Inspection.Plugin.UponFailure