updates to backend module

Add some documentation to the Backend module. Also, add a templateBackend
to make defining custom backends easier. Finally, create the
defaultWordBreakChars value so I don't keep copy-n-pasteing that
stupid string around.

darcs-hash:20070131171054-f399b-d1cbe511a6e57c2039aa1e2ebcd5d2a5f270d2c8

src/System/Console/Shell.hs

@@ -72,18 +72,17 @@ import System.Console.Shell.Types
 import System.Console.Shell.ShellMonad
 import System.Console.Shell.Commands
 import System.Console.Shell.RunShell
-
+import System.Console.Shell.Backend
 
 -- | A basic shell description with sane initial values
 initialShellDescription :: ShellDescription st
 initialShellDescription =
-  let wbc = " \t\n\r\v`~!@#$%^&*()=[]{};\\\'\",<>" in
-    ShDesc
+   ShDesc
        { shellCommands      = []
        , commandStyle       = CharPrefixCommands ':'
        , evaluateFunc       = \_ -> return ()
        , greetingText       = Nothing
-       , wordBreakChars     = wbc
+       , wordBreakChars     = defaultWordBreakChars
        , beforePrompt       = return ()
        , prompt             = \_ -> return "> "
        , secondaryPrompt    = Nothing

src/System/Console/Shell/Backend.hs

@@ -5,12 +5,18 @@
  -}
 
 {- | This module defines the Shellac interface for shell backends.  A shell backend
-     is required to provide sensible implementations for 'flushOutput',
+     is required to provide sensible implementations for 'outputString', 'flushOutput',
      'getSingleChar', 'getInput', and 'getWordBreakChars'.  All other operations may 
      be noops (however, they must not denote bottom!).  
 -}
 
-module System.Console.Shell.Backend where
+module System.Console.Shell.Backend
+( CompletionFunction
+, BackendOutput (..)
+, ShellBackend (..)
+, defaultWordBreakChars
+, templateBackend
+) where
 
 
 -- | The type of completion functions.  The argument is a triple
@@ -38,6 +44,12 @@ data BackendOutput
    | ErrorOutput String        -- ^ An string generated by an error
 
 
+-- | This record type contains all the functions that Shellac allows the pluggable
+--   backend to provide.  Most of these operations are optional andn relate to
+--   advanced features like command completion and history.  However, a shell backend
+--   is required to provide sensible implementations for 'outputString', 'flushOutput',
+--   'getSingleChar', 'getInput', and 'getWordBreakChars'.
+
 data ShellBackend bst
    = ShBackend
      { initBackend                    :: IO bst
@@ -110,3 +122,41 @@ data ShellBackend bst
          -- ^ Write the history buffer to a file.  The file should be formatted in the
          --   same way as in the description for 'readHistory'.
      }
+
+-- | Provides a sane default set of characters to use when breaking
+--   lines into \'words\'.  If a backend does not have configuratble
+--   word break characters, the 'getWordBreakCharacters' can just
+--   return this default set.
+defaultWordBreakChars :: [Char]
+defaultWordBreakChars = " \t\n\r\v`~!@#$%^&*()=[]{};\\\'\",<>"
+
+--  | This backend template is useful for defining custom backends.
+--    The idea is that you will use 'templateBackend' to generate a
+--    bare-bones backend implemenation and only fill in the methods
+--    that you wish to define using the record update syntax.
+--    The parameter to 'templateBackend'
+--    becomes the backend state associated with the backend and is
+--    passed into to each of the operation methods.
+
+templateBackend :: a -> ShellBackend a
+templateBackend bst = ShBackend
+     { initBackend                    = return bst
+     , shutdownBackend                = \_ -> return ()
+     , outputString                   = \_ _ -> return ()
+     , flushOutput                    = \_ -> return ()
+     , getSingleChar                  = \_ _ -> return Nothing
+     , getInput                       = \_ _ -> return Nothing
+     , addHistory                     = \_ _ -> return ()
+     , setWordBreakChars              = \_ _ -> return ()
+     , getWordBreakChars              = \_ -> return defaultWordBreakChars
+     , onCancel                       = \_ -> return ()
+     , setAttemptedCompletionFunction = \_ _ -> return ()
+     , setDefaultCompletionFunction   = \_ _ -> return ()
+     , completeFilename               = \_ _ -> return []
+     , completeUsername               = \_ _ -> return []
+     , clearHistoryState              = \_ -> return ()
+     , setMaxHistoryEntries           = \_ _ -> return ()
+     , getMaxHistoryEntries           = \_ -> return 0
+     , readHistory                    = \_ _ -> return ()
+     , writeHistory                   = \_ _ -> return ()
+     }

src/System/Console/Shell/Backend/Basic.hs

@@ -33,7 +33,7 @@ basicBackend = ShBackend
   , getInput                         = \_ -> basicGetInput
   , addHistory                       = \_ _ -> return ()
   , setWordBreakChars                = \_ _ -> return ()
-  , getWordBreakChars                = \_ -> return " \t\n\r\v`~!@#$%^&*()=[]{};\\\'\",<>"
+  , getWordBreakChars                = \_ -> return defaultWordBreakChars
   , onCancel                         = \_ -> hPutStrLn stdout "canceled...\n"
   , setAttemptedCompletionFunction   = \_ _ -> return ()
   , setDefaultCompletionFunction     = \_ _ -> return ()