System.Console.Ansigraph.Core

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 Graphable type class.

Ansigraph is intended to be used in on of two ways:

• By importing System.Console.Ansigraph. 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]'.
• By directly importing System.Console.Ansigraph.Core, 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: Graph, PosGraph, CGraph, Mat, CMat. They are also available from the standard module.

Core Functionality

The Graphable class

class Graphable a where

Things that ansigraph knows how to render at the terminal are instances of this class.

In general, when ANSI codes are involved, a graphWith 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 colorStr and colorStrLn.

The graphHeight function specifies how many vertical lines a graph occupies and is needed for animations to work properly

Minimal complete definition

graphWith, graphHeight

Methods

graphWith :: MonadIO m => GraphSettings -> a -> m ()

Render a graph to standard output.

graphHeight :: a -> Int

The number of vertical lines a graph occupies.

Instances

Graphable CMat

Methods

graphWith :: MonadIO m => GraphSettings -> CMat -> m ()

graphHeight :: CMat -> Int

Graphable Mat

Methods

graphWith :: MonadIO m => GraphSettings -> Mat -> m ()

graphHeight :: Mat -> Int

Graphable PosGraph

Methods

graphWith :: MonadIO m => GraphSettings -> PosGraph -> m ()

graphHeight :: PosGraph -> Int

Graphable CGraph

Methods

graphWith :: MonadIO m => GraphSettings -> CGraph -> m ()

graphHeight :: CGraph -> Int

Graphable Graph

Methods

graphWith :: MonadIO m => GraphSettings -> Graph -> m ()

graphHeight :: Graph -> Int

graph :: MonadIO m => Graphable a => a -> m ()

Invokes the Graphable type class method graphWith with the default GraphSettings record, graphDefaults.

animateWith :: MonadIO m => Graphable a => GraphSettings -> [a] -> m ()

Any list of a Graphable type can be made into an animation, by graphing each element with a time delay and screen-clear after each. GraphSettings are used to determine the time delta and any coloring/scaling options.

animate :: MonadIO m => Graphable a => [a] -> m ()

Perform animateWith using default options. Equivalent to graphing each member of the supplied list with a short delay and screen-clear after each.

transientAnim :: (MonadIO m, Graphable a) => [a] -> m ()

Like animate, only it does not leave the final frame of the animation visible.

transientAnimWith :: MonadIO m => Graphable a => GraphSettings -> [a] -> m ()

Like animateWith, only it does not leave the final frame of the animation visible.

Graphing options

data GraphSettings

Record that holds graphing options.

Constructors

GraphSettings

Fields

• realColor :: AnsiColor

  Foreground color for real number component.

• imagColor :: AnsiColor

  Foreground color for imaginary number component.

• realNegColor :: AnsiColor

  Foreground color for negative real values. For matrix graphs only.

• imagNegColor :: AnsiColor

  Foreground color for negative imaginary values. For matrix graphs only.

• realBG :: AnsiColor

  Background color for real number component.

• imagBG :: AnsiColor

  Background color for imaginary number component.

• framerate :: Int

  Framerate in FPS.

Default options

graphDefaults :: GraphSettings

Default graph settings.

blue :: AnsiColor

Vivid Blue – used as the default real foreground color.

pink :: AnsiColor

Vivid Magenta – used as the default foreground color for imaginary graph component.

white :: AnsiColor

Vivid White – used as the default graph background color for both real and imaginary graph components.

red :: AnsiColor

Vivid Red – used as the default foreground color for negative real component.

green :: AnsiColor

Dull Green – used as the default foreground color for negative imaginary component.

noColoring :: Coloring

A Coloring representing default terminal colors, i.e. two Nothings.

ANSI data

Basic types from ANSI package

data Color :: *

ANSI colors: come in various intensities, which are controlled by ColorIntensity

Constructors

Black

Red

Green

Yellow

Blue

Magenta

Cyan

White

Instances

Bounded Color

Methods

minBound :: Color

maxBound :: Color

Enum Color

Methods

succ :: Color -> Color

pred :: Color -> Color

toEnum :: Int -> Color

fromEnum :: Color -> Int

enumFrom :: Color -> [Color]

enumFromThen :: Color -> Color -> [Color]

enumFromTo :: Color -> Color -> [Color]

enumFromThenTo :: Color -> Color -> Color -> [Color]

Eq Color

Methods

(==) :: Color -> Color -> Bool

(/=) :: Color -> Color -> Bool

Ord Color

Methods

compare :: Color -> Color -> Ordering

(<) :: Color -> Color -> Bool

(<=) :: Color -> Color -> Bool

(>) :: Color -> Color -> Bool

(>=) :: Color -> Color -> Bool

max :: Color -> Color -> Color

min :: Color -> Color -> Color

Read Color

Methods

readsPrec :: Int -> ReadS Color

readList :: ReadS [Color]

readPrec :: ReadPrec Color

readListPrec :: ReadPrec [Color]

Show Color

Methods

showsPrec :: Int -> Color -> ShowS

show :: Color -> String

showList :: [Color] -> ShowS

Ix Color

Methods

range :: (Color, Color) -> [Color]

index :: (Color, Color) -> Color -> Int

unsafeIndex :: (Color, Color) -> Color -> Int

inRange :: (Color, Color) -> Color -> Bool

rangeSize :: (Color, Color) -> Int

unsafeRangeSize :: (Color, Color) -> Int

data ColorIntensity :: *

ANSI colors come in two intensities

Constructors

Dull

Vivid

Instances

Bounded ColorIntensity

Methods

minBound :: ColorIntensity

maxBound :: ColorIntensity

Enum ColorIntensity

Methods

succ :: ColorIntensity -> ColorIntensity

pred :: ColorIntensity -> ColorIntensity

toEnum :: Int -> ColorIntensity

fromEnum :: ColorIntensity -> Int

enumFrom :: ColorIntensity -> [ColorIntensity]

enumFromThen :: ColorIntensity -> ColorIntensity -> [ColorIntensity]

enumFromTo :: ColorIntensity -> ColorIntensity -> [ColorIntensity]

enumFromThenTo :: ColorIntensity -> ColorIntensity -> ColorIntensity -> [ColorIntensity]

Eq ColorIntensity

Methods

(==) :: ColorIntensity -> ColorIntensity -> Bool

(/=) :: ColorIntensity -> ColorIntensity -> Bool

Ord ColorIntensity

Methods

compare :: ColorIntensity -> ColorIntensity -> Ordering

(<) :: ColorIntensity -> ColorIntensity -> Bool

(<=) :: ColorIntensity -> ColorIntensity -> Bool

(>) :: ColorIntensity -> ColorIntensity -> Bool

(>=) :: ColorIntensity -> ColorIntensity -> Bool

max :: ColorIntensity -> ColorIntensity -> ColorIntensity

min :: ColorIntensity -> ColorIntensity -> ColorIntensity

Read ColorIntensity

Methods

readsPrec :: Int -> ReadS ColorIntensity

readList :: ReadS [ColorIntensity]

readPrec :: ReadPrec ColorIntensity

readListPrec :: ReadPrec [ColorIntensity]

Show ColorIntensity

Methods

showsPrec :: Int -> ColorIntensity -> ShowS

show :: ColorIntensity -> String

showList :: [ColorIntensity] -> ShowS

Ix ColorIntensity

Methods

range :: (ColorIntensity, ColorIntensity) -> [ColorIntensity]

index :: (ColorIntensity, ColorIntensity) -> ColorIntensity -> Int

unsafeIndex :: (ColorIntensity, ColorIntensity) -> ColorIntensity -> Int

inRange :: (ColorIntensity, ColorIntensity) -> ColorIntensity -> Bool

rangeSize :: (ColorIntensity, ColorIntensity) -> Int

unsafeRangeSize :: (ColorIntensity, ColorIntensity) -> Int

Custom composite data types

data AnsiColor

ANSI colors are characterized by a Color and a ColorIntensity.

Constructors

AnsiColor

Fields

• intensity :: ColorIntensity
• color :: Color

Instances

Show AnsiColor

Methods

showsPrec :: Int -> AnsiColor -> ShowS

show :: AnsiColor -> String

showList :: [AnsiColor] -> ShowS

data Coloring

Holds two Maybe AnsiColors representing foreground and background colors for display via ANSI. Nothing means use the default terminal color.

Constructors

Coloring

Fields

• foreground :: Maybe AnsiColor
• background :: Maybe AnsiColor

Instances

Show Coloring

Methods

showsPrec :: Int -> Coloring -> ShowS

show :: Coloring -> String

showList :: [Coloring] -> ShowS

ANSI helpers

mkColoring :: AnsiColor -> AnsiColor -> Coloring

Helper constructor function for Coloring that takes straight AnsiColors without Maybe.

fromFG :: AnsiColor -> Coloring

Easily create a Coloring by specifying the foreground AnsiColor and no custom background.

fromBG :: AnsiColor -> Coloring

Easily create a Coloring by specifying the background AnsiColor and no custom foreground.

realColors :: GraphSettings -> Coloring

Projection retrieving foreground and background colors for real number graphs in the form of a Coloring.

imagColors :: GraphSettings -> Coloring

Projection retrieving foreground and background colors for imaginary component of complex number graphs in the form of a Coloring.

colorSets :: GraphSettings -> (Coloring, Coloring)

Retrieves a pair of Colorings for real and imaginary graph components respectively.

invert :: Coloring -> Coloring

Swaps foreground and background colors within a Coloring.

interpAnsiColor :: ConsoleLayer -> AnsiColor -> SGR

The SGR command corresponding to a particular ConsoleLayer and AnsiColor.

setColor :: MonadIO m => ConsoleLayer -> AnsiColor -> m ()

Set the given AnsiColor on the given ConsoleLayer.

clear :: MonadIO m => m ()

Clear any SGR settings and then flush stdout.

clearLn :: MonadIO m => m ()

Clear any SGR settings, flush stdout and print a new line.

applyColoring :: MonadIO m => Coloring -> m ()

Apply both foreground and background color contained in a Coloring.

colorStr :: MonadIO m => Coloring -> String -> m ()

Use a particular ANSI Coloring to print a string at the terminal (without a new line), then clear all ANSI SGR codes and flush stdout.

colorStrLn :: MonadIO m => Coloring -> String -> m ()

Use a particular ANSI Coloring to print a string at the terminal, then clear all ANSI SGR codes, flush stdout and print a new line.

boldStr :: MonadIO m => Coloring -> String -> m ()

Like colorStr but prints bold text.

boldStrLn :: MonadIO m => Coloring -> String -> m ()

Like colorStrLn but prints bold text.

Graphable wrapper types

newtype Graph

Wrapper type for graph of a real vector/function.

Constructors

Graph

Fields

• unGraph :: [Double]

Instances

Graphable Graph

Methods

graphWith :: MonadIO m => GraphSettings -> Graph -> m ()

graphHeight :: Graph -> Int

newtype CGraph

Wrapper type for graph of a complex vector/function.

Constructors

CGraph

Fields

• unCGraph :: [Complex Double]

Instances

Graphable CGraph

Methods

graphWith :: MonadIO m => GraphSettings -> CGraph -> m ()

graphHeight :: CGraph -> Int

newtype PosGraph

Wrapper type for graph of a non-negative real vector/function.

Constructors

PosGraph

Fields

• unPosGraph :: [Double]

Instances

Graphable PosGraph

Methods

graphWith :: MonadIO m => GraphSettings -> PosGraph -> m ()

graphHeight :: PosGraph -> Int

newtype Mat

Wrapper type for graph of a real two-index vector/two-argument function.

Constructors

Mat

Fields

• unMat :: [[Double]]

Instances

Graphable Mat

Methods

graphWith :: MonadIO m => GraphSettings -> Mat -> m ()

graphHeight :: Mat -> Int

newtype CMat

Wrapper type for graph of a complex two-index vector/two-argument function.

Constructors

CMat

Fields

• unCMat :: [[Complex Double]]

Instances

Graphable CMat

Methods

graphWith :: MonadIO m => GraphSettings -> CMat -> m ()

graphHeight :: CMat -> Int

Graphing

Horizontal vector graphing (IO actions)

displayPV :: MonadIO m => GraphSettings -> [Double] -> m ()

ANSI based display for positive real vectors. Primarily invoked via graph, graphWith, animate, animateWith.

displayRV :: MonadIO m => GraphSettings -> [Double] -> m ()

ANSI based display for real vectors. Primarily invoked via graph, graphWith, animate, animateWith.

displayCV :: MonadIO m => GraphSettings -> [Complex Double] -> m ()

ANSI based display for complex vectors. Primarily invoked via graph, graphWith, animate, animateWith.

Horizontal rendering logic (producing strings)

renderPV :: [Double] -> String

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 display functions are preferable for most use cases.

renderRV :: [Double] -> (String, String)

Simple real vector rendering as a pair of strings. The IO display functions are preferable for most use cases.

renderCV :: [Complex Double] -> (String, String, String, String)

Simple complex vector rendering as a pair of strings. The IO display functions are preferable for most use cases.

Matrix graphing

displayMat :: MonadIO m => GraphSettings -> [[Double]] -> m ()

Use ANSI coloring (specified by an GraphSettings) to visually display a Real matrix.

displayCMat :: MonadIO m => GraphSettings -> [[Complex Double]] -> m ()

Use ANSI coloring (specified by an GraphSettings) to visually display a Complex matrix.

matShow :: [[Double]] -> [String]

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.

Simple (non-ANSI) graphing for strictly-positive data

posGraph :: MonadIO m => [Double] -> m ()

Display a graph of the supplied (non-negative) real vector.

posAnim :: MonadIO m => [[Double]] -> m ()

Display an animation of the supplied list of (non-negative) real vectors.

For clearing

clearBack :: MonadIO m => Int -> m ()

Clear the last n lines of terminal text. Used to make graph animations. Rexported as a handy convenience for other uses.