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


-- | Terminal-based graphing via ANSI and Unicode
--   
--   Ansigraph is an ultralightweight terminal-based graphing utility. It
--   uses Unicode characters and ANSI escape codes to display and animate
--   colored graphs of vectors/functions in real and complex variables.
--   
--   This functionality is provided by a <a>Graphable</a> type class, whose
--   method <a>graphWith</a> draws a graph at the terminal. Another
--   function <a>animateWith</a> takes a list of Graphable elements and
--   displays an animation by rendering them in sequence. Both of these
--   functions take an options record as an argument. The <a>graph</a> and
--   <a>animate</a> functions are defined to use the default options, and
--   the user can define similar functions based on their own settings.
--   
--   There are two main ways to use the package. Importing
--   <a>System.Console.Ansigraph</a> provides all the functionality we
--   typically use. This includes the <i>FlexibleInstances</i> extension,
--   which makes it marginally more convenient to use graphing functions by
--   allowing instances like 'Graphable [Double]'.
--   
--   If you want to use the package without activating
--   <i>FlexibleInstances</i> then you can import
--   <a>System.Console.Ansigraph.Core</a>, which provides everything except
--   these instances. Then you must use one of a few newtype wrappers,
--   namely: <a>Graph</a>, <a>PosGraph</a>, <a>CGraph</a>, <a>Mat</a>,
--   <a>CMat</a>. These wrappers are also available from the standard
--   <a>Ansigraph</a> module.
--   
--   The <a>System.Console.Ansigraph.Examples</a> module contains examples
--   of all the graph types, and also shows the available ANSI colors.
@package ansigraph
@version 0.3.0.5


-- | This module provides the core functionality of the ansigraph package:
--   terminal-based graphing for vectors and matrices of real and complex
--   numbers.
--   
--   This is implemented via a <a>Graphable</a> type class.
--   
--   <b>Ansigraph is intended to be used in on of two ways:</b>
--   
--   <ul>
--   <li><b>By importing <a>System.Console.Ansigraph</a></b>. This provides
--   all the functionality we typically use, including the
--   FlexibleInstances extension which makes it easier to use graphing
--   functions by allowing instances like 'Graphable [Double]'.</li>
--   <li><b>By directly importing <a>System.Console.Ansigraph.Core</a></b>,
--   which does not activate FlexibleInstances but includes everything else
--   provided by the other module. This just means you must use one of a
--   few newtype wrappers, namely: <a>Graph</a>, <a>PosGraph</a>,
--   <a>CGraph</a>, <a>Mat</a>, <a>CMat</a>. They are also available from
--   the standard module.</li>
--   </ul>
module System.Console.Ansigraph.Core

-- | Things that ansigraph knows how to render at the terminal are
--   instances of this class.
--   
--   In general, when ANSI codes are involved, a <a>graphWith</a> method
--   should fush stdout when finished, and whenever codes are invoked to
--   i.e. change terminal colors. This is easily handled by defining it in
--   terms of <a>colorStr</a> and <a>colorStrLn</a>.
--   
--   The <a>graphHeight</a> function specifies how many vertical lines a
--   graph occupies and is needed for animations to work properly
class Graphable a

-- | Render a graph to standard output.
graphWith :: (Graphable a, MonadIO m) => GraphSettings -> a -> m ()

-- | The number of vertical lines a graph occupies.
graphHeight :: Graphable a => a -> Int

-- | Invokes the <a>Graphable</a> type class method <a>graphWith</a> with
--   the default <a>GraphSettings</a> record, <a>graphDefaults</a>.
graph :: MonadIO m => Graphable a => a -> m ()

-- | Any list of a <a>Graphable</a> type can be made into an animation, by
--   <a>graph</a>ing each element with a time delay and screen-clear after
--   each. <a>GraphSettings</a> are used to determine the time delta and
--   any coloring/scaling options.
animateWith :: MonadIO m => Graphable a => GraphSettings -> [a] -> m ()

-- | Perform <a>animateWith</a> using default options. Equivalent to
--   <a>graph</a>ing each member of the supplied list with a short delay
--   and screen-clear after each.
animate :: MonadIO m => Graphable a => [a] -> m ()

-- | Like <a>animate</a>, only it does not leave the final frame of the
--   animation visible.
transientAnim :: (MonadIO m, Graphable a) => [a] -> m ()

-- | Like <a>animateWith</a>, only it does not leave the final frame of the
--   animation visible.
transientAnimWith :: MonadIO m => Graphable a => GraphSettings -> [a] -> m ()

-- | Record that holds graphing options.
data GraphSettings
GraphSettings :: AnsiColor -> AnsiColor -> AnsiColor -> AnsiColor -> AnsiColor -> AnsiColor -> Int -> GraphSettings

-- | Foreground color for real number component.
[realColor] :: GraphSettings -> AnsiColor

-- | Foreground color for imaginary number component.
[imagColor] :: GraphSettings -> AnsiColor

-- | Foreground color for negative real values. For matrix graphs only.
[realNegColor] :: GraphSettings -> AnsiColor

-- | Foreground color for negative imaginary values. For matrix graphs
--   only.
[imagNegColor] :: GraphSettings -> AnsiColor

-- | Background color for real number component.
[realBG] :: GraphSettings -> AnsiColor

-- | Background color for imaginary number component.
[imagBG] :: GraphSettings -> AnsiColor

-- | Framerate in FPS.
[framerate] :: GraphSettings -> Int

-- | Default graph settings.
graphDefaults :: GraphSettings

-- | <a>Vivid</a> <a>Blue</a> – used as the default real foreground color.
blue :: AnsiColor

-- | <a>Vivid</a> <a>Magenta</a> – used as the default foreground color for
--   imaginary graph component.
pink :: AnsiColor

-- | <a>Vivid</a> <a>White</a> – used as the default graph background color
--   for both real and imaginary graph components.
white :: AnsiColor

-- | <a>Vivid</a> <a>Red</a> – used as the default foreground color for
--   negative real component.
red :: AnsiColor

-- | <a>Dull</a> <a>Green</a> – used as the default foreground color for
--   negative imaginary component.
green :: AnsiColor

-- | A <a>Coloring</a> representing default terminal colors, i.e. two
--   <a>Nothing</a>s.
noColoring :: Coloring

-- | ANSI colors: come in various intensities, which are controlled by
--   <a>ColorIntensity</a>
data Color :: *
Black :: Color
Red :: Color
Green :: Color
Yellow :: Color
Blue :: Color
Magenta :: Color
Cyan :: Color
White :: Color

-- | ANSI colors come in two intensities
data ColorIntensity :: *
Dull :: ColorIntensity
Vivid :: ColorIntensity

-- | ANSI colors are characterized by a <a>Color</a> and a
--   <a>ColorIntensity</a>.
data AnsiColor
AnsiColor :: ColorIntensity -> Color -> AnsiColor
[intensity] :: AnsiColor -> ColorIntensity
[color] :: AnsiColor -> Color

-- | Holds two <a>Maybe</a> <a>AnsiColor</a>s representing foreground and
--   background colors for display via ANSI. <a>Nothing</a> means use the
--   default terminal color.
data Coloring
Coloring :: Maybe AnsiColor -> Maybe AnsiColor -> Coloring
[foreground] :: Coloring -> Maybe AnsiColor
[background] :: Coloring -> Maybe AnsiColor

-- | Helper constructor function for <a>Coloring</a> that takes straight
--   <a>AnsiColor</a>s without <a>Maybe</a>.
mkColoring :: AnsiColor -> AnsiColor -> Coloring

-- | Easily create a <a>Coloring</a> by specifying the foreground
--   <a>AnsiColor</a> and no custom background.
fromFG :: AnsiColor -> Coloring

-- | Easily create a <a>Coloring</a> by specifying the background
--   <a>AnsiColor</a> and no custom foreground.
fromBG :: AnsiColor -> Coloring

-- | Projection retrieving foreground and background colors for real number
--   graphs in the form of a <a>Coloring</a>.
realColors :: GraphSettings -> Coloring

-- | Projection retrieving foreground and background colors for imaginary
--   component of complex number graphs in the form of a <a>Coloring</a>.
imagColors :: GraphSettings -> Coloring

-- | Retrieves a pair of <a>Coloring</a>s for real and imaginary graph
--   components respectively.
colorSets :: GraphSettings -> (Coloring, Coloring)

-- | Swaps foreground and background colors within a <a>Coloring</a>.
invert :: Coloring -> Coloring

-- | The SGR command corresponding to a particular <a>ConsoleLayer</a> and
--   <a>AnsiColor</a>.
interpAnsiColor :: ConsoleLayer -> AnsiColor -> SGR

-- | Set the given <a>AnsiColor</a> on the given <a>ConsoleLayer</a>.
setColor :: MonadIO m => ConsoleLayer -> AnsiColor -> m ()

-- | Clear any SGR settings and then flush stdout.
clear :: MonadIO m => m ()

-- | Clear any SGR settings, flush stdout and print a new line.
clearLn :: MonadIO m => m ()

-- | Apply both foreground and background color contained in a
--   <a>Coloring</a>.
applyColoring :: MonadIO m => Coloring -> m ()

-- | Use a particular ANSI <a>Coloring</a> to print a string at the
--   terminal (without a new line), then clear all ANSI SGR codes and flush
--   stdout.
colorStr :: MonadIO m => Coloring -> String -> m ()

-- | Use a particular ANSI <a>Coloring</a> to print a string at the
--   terminal, then clear all ANSI SGR codes, flush stdout and print a new
--   line.
colorStrLn :: MonadIO m => Coloring -> String -> m ()

-- | Like <a>colorStr</a> but prints bold text.
boldStr :: MonadIO m => Coloring -> String -> m ()

-- | Like <a>colorStrLn</a> but prints bold text.
boldStrLn :: MonadIO m => Coloring -> String -> m ()

-- | Wrapper type for graph of a real vector/function.
newtype Graph
Graph :: [Double] -> Graph
[unGraph] :: Graph -> [Double]

-- | Wrapper type for graph of a complex vector/function.
newtype CGraph
CGraph :: [Complex Double] -> CGraph
[unCGraph] :: CGraph -> [Complex Double]

-- | Wrapper type for graph of a non-negative real vector/function.
newtype PosGraph
PosGraph :: [Double] -> PosGraph
[unPosGraph] :: PosGraph -> [Double]

-- | Wrapper type for graph of a real two-index vector/two-argument
--   function.
newtype Mat
Mat :: [[Double]] -> Mat
[unMat] :: Mat -> [[Double]]

-- | Wrapper type for graph of a complex two-index vector/two-argument
--   function.
newtype CMat
CMat :: [[Complex Double]] -> CMat
[unCMat] :: CMat -> [[Complex Double]]

-- | ANSI based display for positive real vectors. Primarily invoked via
--   <tt>graph</tt>, <tt>graphWith</tt>, <tt>animate</tt>,
--   <tt>animateWith</tt>.
displayPV :: MonadIO m => GraphSettings -> [Double] -> m ()

-- | ANSI based display for real vectors. Primarily invoked via
--   <tt>graph</tt>, <tt>graphWith</tt>, <tt>animate</tt>,
--   <tt>animateWith</tt>.
displayRV :: MonadIO m => GraphSettings -> [Double] -> m ()

-- | ANSI based display for complex vectors. Primarily invoked via
--   <tt>graph</tt>, <tt>graphWith</tt>, <tt>animate</tt>,
--   <tt>animateWith</tt>.
displayCV :: MonadIO m => GraphSettings -> [Complex Double] -> m ()

-- | Simple vector to String rendering that assumes positive input. Yields
--   String of Unicode chars representing graph bars varying in units of
--   1/8. The IO <tt>display</tt> functions are preferable for most use
--   cases.
renderPV :: [Double] -> String

-- | Simple real vector rendering as a pair of strings. The IO
--   <tt>display</tt> functions are preferable for most use cases.
renderRV :: [Double] -> (String, String)

-- | Simple complex vector rendering as a pair of strings. The IO
--   <tt>display</tt> functions are preferable for most use cases.
renderCV :: [Complex Double] -> (String, String, String, String)

-- | Use ANSI coloring (specified by an <a>GraphSettings</a>) to visually
--   display a Real matrix.
displayMat :: MonadIO m => GraphSettings -> [[Double]] -> m ()

-- | Use ANSI coloring (specified by an <a>GraphSettings</a>) to visually
--   display a Complex matrix.
displayCMat :: MonadIO m => GraphSettings -> [[Complex Double]] -> m ()

-- | Given a matrix of Doubles, return the list of strings illustrating the
--   absolute value of each entry relative to the largest, via unicode
--   chars that denote a particular density. Used for testing purposes.
matShow :: [[Double]] -> [String]

-- | Display a graph of the supplied (non-negative) real vector.
posGraph :: MonadIO m => [Double] -> m ()

-- | Display an animation of the supplied list of (non-negative) real
--   vectors.
posAnim :: MonadIO m => [[Double]] -> m ()

-- | Clear the last <tt>n</tt> lines of terminal text. Used to make graph
--   animations. Rexported as a handy convenience for other uses.
clearBack :: MonadIO m => Int -> m ()
instance System.Console.Ansigraph.Core.Graphable System.Console.Ansigraph.Core.CMat
instance System.Console.Ansigraph.Core.Graphable System.Console.Ansigraph.Core.Mat
instance System.Console.Ansigraph.Core.Graphable System.Console.Ansigraph.Core.PosGraph
instance System.Console.Ansigraph.Core.Graphable System.Console.Ansigraph.Core.CGraph
instance System.Console.Ansigraph.Core.Graphable System.Console.Ansigraph.Core.Graph


-- | This is the primary module to import for use of the ansigraph package,
--   which provides terminal-based graphing for vectors and matrices of
--   real and complex numbers.
--   
--   This functionality is implemented via a <a>Graphable</a> type class.
--   
--   <b>Ansigraph is intended to be used in on of two ways:</b>
--   
--   <ul>
--   <li><b>By importing <a>System.Console.Ansigraph</a></b>. This provides
--   all the functionality we typically use, including the
--   FlexibleInstances extension which makes it easier to use graphing
--   functions by allowing instances like 'Graphable [Double]'. It also
--   provides <a>System.Console.AnsiGraph.Core</a> which provides all the
--   core functionality. See the Haddock page for that module for more
--   details.</li>
--   <li><b>By directly importing <a>System.Console.Ansigraph.Core</a></b>,
--   which does not activate FlexibleInstances but includes everything else
--   provided by the other module. This just means you must use one of a
--   few newtype wrappers, namely: <a>Graph</a>, <a>PosGraph</a>,
--   <a>CGraph</a>, <a>Mat</a>, <a>CMat</a>. They are also available from
--   the standard module.</li>
--   </ul>
module System.Console.Ansigraph


-- | A module that shows some simple examples demonstrating how to use the
--   package.
module System.Console.Ansigraph.Examples

-- | Run all of the demos in sequence.
demo :: IO ()

-- | Displays a legend showing color conventions for supported graph types.
legend :: IO ()

-- | Show all of the available <a>AnsiColor</a>s with corresponding
--   <a>ColorIntensity</a>, <a>Color</a> pairs.
showColors :: IO ()

-- | Display an animation of the complex wave <i>z(x,t) = exp(ix - it)</i>
--   in some units.
waveDemoComplex :: IO ()

-- | Display an animation of the real function <i>r(x,t) = cos(x-t)</i> in
--   the standard style, i.e. with both positive and negative regions.
waveDemoReal :: IO ()

-- | Display an animation of the positive real function <i>p(x,t) =
--   cos(x-t) + 1</i> in some units.
waveDemoPositive :: IO ()

-- | A complex wave vector, part of the graph of <i>z(x,t) = exp(ix -
--   it)</i> in some units.
wave :: [Complex Double]

-- | An example real matrix animation.
matDemoReal :: IO ()

-- | Shows an animation of an example time-dependent matrix formed from
--   Pauli matrices, called <a>unitary</a>. Specifically, it is the tensor
--   product of σz and σx exponentiated with different frequencies.
matDemoComplex :: IO ()

-- | An example of a time-dependent complex matrix.
unitary :: Double -> [[Complex Double]]
