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


-- | Trivial wrapper over ansi-terminal.
--   
--   This trivial package presents a simplified interface to the most
--   excellent <tt>ansi-terminal</tt> package, exposing only the
--   functionallity that I personally use. It is very limited, but very
--   easy to use.
--   
--   This package allows you to manipulate the text output terminal
--   (assuming your program has one). Specifically, it supports colour
--   changes and title changes (for virtual terminals). Impressively, it
--   (or rather, the package it wraps) works on both Windows and Unix.
--   Under Windows, it uses native Win32 calls, while under Unix it uses
--   ANSI escape codes.
@package AC-Terminal
@version 1.0


-- | This module provides the basic features of the package.
module System.Terminal.Core

-- | Possible terminal colours. (D for Dark, L for Light.)
data Colour
DBlack :: Colour
DBlue :: Colour
DGreen :: Colour
DCyan :: Colour
DRed :: Colour
DMagenta :: Colour
DYellow :: Colour
DWhite :: Colour
LBlack :: Colour
LBlue :: Colour
LGreen :: Colour
LCyan :: Colour
LRed :: Colour
LMagenta :: Colour
LYellow :: Colour
LWhite :: Colour

-- | Set terminal forground and background colours.
--   
--   Note that under Windows, the change in colour takes place immediately.
--   You may need to flush <tt>stdout</tt> before calling this function.
--   (This is not necessary under Unix, but it's probably good practise to
--   do it for portability's sake.)
set_colours :: Colour -> Colour -> IO ()

-- | Change the title of the [virtual] terminal.
set_title :: String -> IO ()
instance Enum Colour


-- | This module provides various utilities and short-cuts.
module System.Terminal.Utility

-- | Set terminal foreground colour (background is set to black).
set_colour :: Colour -> IO ()

-- | Set default terminal colours (DWhite on DBlack).
set_colours_default :: IO ()

-- | Set terminal [foreground] colour and then <a>putStrLn</a> a string.
putStrLnC :: Colour -> String -> IO ()

-- | Write a pair of text strings on a single line, with different
--   [foreground] text colours.
putPairLn :: (Colour, String) -> (Colour, String) -> IO ()

-- | Print a single line of text, with a given character highlighted in
--   colour. Useful for, say, highlighting the location of a syntax error
--   in an expression.
--   
--   The tuple consists of three colour pairs. Each pair is a
--   foreground/background pair. The first pair applies to the next before
--   the nominated position, the second pair applies to the nominated
--   position itself, and the third pair applies to any text after the
--   nominated position.
--   
--   The nominated position is given by the <a>Int</a> argument, with 0
--   being the very first character of the string. Note that if the
--   position is off the end of the string, a blank space will be added to
--   the end of the string and <i>that</i> will be highlighted.
--   
--   Note that no newline is written. If you want one, you must output it
--   yourself.
highlight :: ((Colour, Colour), (Colour, Colour), (Colour, Colour)) -> Int -> String -> IO ()

-- | A version of <a>highlight</a> that outputs a newline after the final
--   character of text.
highlightLN :: ((Colour, Colour), (Colour, Colour), (Colour, Colour)) -> Int -> String -> IO ()

-- | A default top-level exception handler, for exceptions that fail to be
--   caught before reaching the top level.
--   
--   In a properly designed application, exceptions should be anticipated,
--   caught and handled in the correct place. (E.g., if you try to open a
--   file, you should anticipate the possibility of an I/O exception and
--   catch/process this appropriately.) Thus an exception reaching the
--   top-level of the program would indicate a programming bug, and the
--   generated error message reflects this. On a crash, the text
--   
--   <pre>
--   An internal program malfunction has occurred.
--   Please report this as a bug to the program developers.
--   </pre>
--   
--   will be emitted on <tt>stderr</tt>, coloured bright yellow on a bright
--   red background. The exception is then re-thrown (presumably halting
--   the program).
default_exception_handler :: Exception e => e -> IO x

-- | Take an <a>IO</a> action, and run it with the
--   <a>default_exception_handler</a> installed. Typically you would do
--   something like
--   
--   <pre>
--   main = with_default_exception_handler main2
--   
--   main2 = do ...
--   </pre>
--   
--   Now all unhandled exceptions in your program will cause a suitable
--   message to be written to <tt>stderr</tt>.
with_default_exception_handler :: IO x -> IO x

module System.Terminal