more documentation updates

Ignore-this: d43cbeedd6c1d2cad49b693ec8e92767

darcs-hash:20100907045642-f0a0d-d65dc6321ab47fb92e2d89f9e385234b1a45071b.gz

src/Graphics/Vty/Inline.hs

@@ -1,3 +1,25 @@
+-- | The inline module provides a limited interface to changing the style of terminal output. The
+-- intention is for this interface to be used inline with other output systems. 
+--
+-- The changes specified by the InlineM monad are applied to the terminals display attributes. These
+-- display attributes effect the display of all following text output to the terminal file
+-- descriptor.
+--
+-- For example, in an IO monad the following code with print the text \"Not styled. \" Followed by the
+-- text \" Styled! \" drawn over a red background and underlined.
+--
+-- @
+--      t <- terminal_handle
+--      putStr \"Not styled. \"
+--      put_attr_change t $ do
+--          back_color red 
+--          apply_style underline
+--      putStr \" Styled! \"
+--      put_attr_change t $ default_all
+--      putStrLn \"Not styled.\"
+--      release_terminal t
+-- @
+--
 -- Copyright 2009-2010 Corey O'Connor
 {-# LANGUAGE BangPatterns #-}
 module Graphics.Vty.Inline ( module Graphics.Vty.Inline
@@ -20,15 +42,24 @@ import System.IO
 
 type InlineM v = State Attr v
 
+-- | Set the background color to the provided 'Color'
 back_color :: Color -> InlineM ()
 back_color c = modify $ flip mappend ( current_attr `with_back_color` c )
 
+-- | Set the foreground color to the provided 'Color'
 fore_color :: Color -> InlineM ()
 fore_color c = modify $ flip mappend ( current_attr `with_fore_color` c )
 
+-- | Attempt to change the 'Style' of the following text.
+--
+-- If the terminal does not support the style change no error is produced. The style can still be
+-- removed.
 apply_style :: Style -> InlineM ()
 apply_style s = modify $ flip mappend ( current_attr `with_style` s )
 
+-- | Attempt to remove the specified 'Style' from the display of the following text.
+--
+-- This will fail if apply_style for the given style has not been previously called. 
 remove_style :: Style -> InlineM ()
 remove_style s_mask = modify $ \attr -> 
     let style' = case attr_style attr of
@@ -37,9 +68,13 @@ remove_style s_mask = modify $ \attr ->
                     SetTo s -> s .&. complement s_mask
     in attr { attr_style = SetTo style' } 
 
+-- | Reset the display attributes
 default_all :: InlineM ()
 default_all = put def_attr
 
+-- | Apply the provided display attribute changes to the terminal.
+--
+-- This also flushes the 'stdout' handle.
 put_attr_change :: ( Applicative m, MonadIO m ) => TerminalHandle -> InlineM () -> m ()
 put_attr_change t c = do
     bounds <- display_bounds t
@@ -60,10 +95,3 @@ put_attr_change t c = do
     liftIO $ modifyIORef ( state_ref t ) $ \s -> s { known_fattr = Just fattr' }
     inline_hack d
 
-put_string :: ( Applicative m, MonadIO m ) => TerminalHandle -> String -> m ()
-put_string t s = do
-    let s_utf8 = UTF8.fromString s
-    liftIO $ hFlush stdout
-    liftIO $ marshall_to_terminal t ( utf8_text_required_bytes s_utf8)
-                                    ( serialize_utf8_text s_utf8 )
-

src/Graphics/Vty/Terminal.hs

@@ -1,17 +1,23 @@
+--  | Generic Terminal interface.
+--
+--  Defines the common interface supported by all terminals.
+--
+--  See also:
+--
+--  1. Graphics.Vty.Terminal: This instantiates an abtract interface to the terminal interface based
+--  on the TERM and COLORTERM environment variables. 
+--  
+--  2. Graphics.Vty.Terminal.Generic: Defines the generic interface all terminals need to implement.
+--
+--  3. Graphics.Vty.Terminal.TerminfoBased: Defines a terminal instance that uses terminfo for all
+--  control strings.  No attempt is made to change the character set to UTF-8 for these terminals.
+--  I don't know a way to reliably determine if that is required or how to do so.
+--
+--  4. Graphics.Vty.Terminal.XTermColor: This module contains an interface suitable for xterm-like
+--  terminals. These are the terminals where TERM == xterm. This does use terminfo for as many
+--  control codes as possible. 
+--
 -- Copyright 2009-2010 Corey O'Connor
---      * Graphics.Vty.Terminal: This instantiates an abtract interface to the terminal interface
---      based on the TERM and COLORTERM environment variables. 
---      * Graphics.Vty.Terminal.Generic: Defines the generic interface all terminals need to implement.
---      * Graphics.Vty.Terminal.TerminfoBased: Defines a terminal instance that uses terminfo for all
---      control strings. 
---          - No attempt is made to change the character set to UTF-8 for these terminals. I don't
---          know a way to reliably determine if that is required or how to do so.
---      * Graphics.Vty.Terminal.XTermColor: This module contains an interface suitable for
---      xterm-like terminals. These are the terminals where TERM == xterm. This does use terminfo
---      for as many control codes as possible. H: This should derive functionality from the
---      TerminfoBased terminal.
---
---
 {-# LANGUAGE ScopedTypeVariables #-}
 module Graphics.Vty.Terminal ( module Graphics.Vty.Terminal
                              , Terminal(..)
@@ -67,6 +73,9 @@ import System.Environment
 -- environment variables (I think?) this assumes that XTERM_VERSION will never be set for a true
 -- Terminal.app or iTerm.app session.
 --
+--
+-- The file descriptor used for output will a duplicate of the current stdout file descriptor.
+--
 -- todo: add an implementation for windows that does not depend on terminfo. Should be installable
 -- with only what is provided in the haskell platform.
 --

src/Graphics/Vty/Terminal/TerminfoBased.hs

@@ -171,7 +171,7 @@ instance Terminal Term where
             ( w, h )    | w < 0 || h < 0 -> fail $ "getwinsize returned < 0 : " ++ show raw_size
                         | otherwise      -> return $ DisplayRegion (toEnum w) (toEnum h)
 
-    -- Output the byte buffer of the specified size to the terminal device.
+    -- | Output the byte buffer of the specified size to the terminal device.
     output_byte_buffer t out_ptr out_byte_count = do
         -- if the out fd is actually the same as stdout's then a
         -- flush is required *before* the c_output_byte_buffer call