[Pkg-haskell-commits] [SCM] haskell-testpack branch, master, updated. debian/1.0.2-1-4-gb0d6b36

John Goerzen jgoerzen at complete.org
Fri Apr 23 14:50:53 UTC 2010


The following commit has been merged in the master branch:
commit b2ef579058863b034619ecb5e07ee2aeff137e10
Author: John Goerzen <jgoerzen at complete.org>
Date:   Thu Dec 16 22:58:55 2004 +0100

    Documented and renamed HVIO
    
    Keywords:
    
    
    (jgoerzen at complete.org--projects/missingh--head--0.7--patch-79)

diff --git a/ChangeLog b/ChangeLog
index 698a27a..07d70e2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,6 +2,22 @@
 # arch-tag: automatic-ChangeLog--jgoerzen at complete.org--projects/missingh--head--0.7
 #
 
+2004-12-16 15:58:55 GMT	John Goerzen <jgoerzen at complete.org>	patch-79
+
+    Summary:
+      Documented and renamed HVIO
+    Revision:
+      missingh--head--0.7--patch-79
+
+
+    modified files:
+     ChangeLog libsrc/MissingH/IO/HVIO.hs
+
+    renamed files:
+     libsrc/MissingH/HVIO.hs
+       ==> libsrc/MissingH/IO/HVIO.hs
+
+
 2004-12-15 22:59:35 GMT	John Goerzen <jgoerzen at complete.org>	patch-78
 
     Summary:
diff --git a/libsrc/MissingH/HVIO.hs b/libsrc/MissingH/IO/HVIO.hs
similarity index 71%
rename from libsrc/MissingH/HVIO.hs
rename to libsrc/MissingH/IO/HVIO.hs
index c67bdb8..45c8824 100644
--- a/libsrc/MissingH/HVIO.hs
+++ b/libsrc/MissingH/IO/HVIO.hs
@@ -17,7 +17,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 -}
 
 {- |
-   Module     : MissingH.HVIO
+   Module     : MissingH.IO.HVIO
    Copyright  : Copyright (C) 2004 John Goerzen
    License    : GNU GPL, version 2 or above
 
@@ -26,13 +26,93 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    Stability  : provisional
    Portability: portable
 
-Haskell Virtual I\/O system main file
+Haskell Virtual I\/O -- a system to increase the flexibility of input and
+output in Haskell
 
 Copyright (c) 2004 John Goerzen, jgoerzen\@complete.org
 
+HVIO provides the following general features:
+
+ * The ability to use a single set of functions on various different
+   types of objects, including standard Handles, in-memory buffers,
+   compressed files, network data streams, etc.
+
+ * The ability to transparently add filters to the I\/O process.
+   These filters could include things such as character set conversions,
+   compression or decompression of a data stream, and more.
+
+ * The ability to define new objects that have the properties
+   of I\/O objects and can be used interchangably with them.
+
+ * Specification compatibility with, and complete support for,
+   existing I\/O on Handles.
+
+ * Provide easier unit testing capabilities for I\/O actions
+
+HVIO defines several basic type classes that you can use.  You will mostly
+be interested in 'HVIOReader', 'HVIOWriter', and 'HVIOSeeker'.  Objects that
+support reading will be an instance of 'HVIOReader'; those that suport writing,
+'HVIOWriter'; and those that support seeking (random access), 'HVIOSeeker'.
+Some, such as Handle, will be an instance of all of these.
+
+It's trivial to adapt old code to work with HVIO.  For instance, consider
+this example of old and new code:
+
+>printMsg :: Handle -> String -> IO ()
+>printMsg h msg = hPutStr h ("msg: " ++ msg)
+
+And now, the new way:
+
+>printMsg :: HVIOWriter h => h -> String -> IO ()
+>printMsg h msg = vPutStr h ("msg: " ++ msg)
+
+There are several points to note about this conversion:
+
+ * The new method can still accept a Handle in exactly the same way as
+   the old method.  Changing your functions to use HVIO will require no
+   changes from functions that call them with Handles.
+
+ * Most \"h\" functions have equivolent \"v\" functions that operate
+   on HVIO classes instead of the more specific Handle.  The \"v\" functions
+   behave identically to the \"h\" functions whenever possible.
+
+ * There is no equivolent of \"openFile\" in any HVIO class.  You must
+   create your Handle (or other HVIO object) using normal means.
+   This is because the creation is so different that it cannot be standardized.
+
+In addition to Handle, there are several pre-defined classes for your use.
+'StreamReader' is a particularly interesting one.  At creation time, you pass
+it a String.  Its contents are read lazily whenever a read call is made.  It
+can be used, therefore, to implement filters (simply initialize it with the
+result from, say, a map over hGetContents from another HVIO object), codecs,
+and simple I\/O testing.  Because it is lazy, it need not hold the entire
+string in memory.  You can create a 'StreamReader' with a call to
+'newStreamReader'.
+
+'MemoryBuffer' is a similar class, but with a different purpose.  It provides
+a full interface like Handle (it implements 'HVIOReader', 'HVIOWriter',
+and 'HVIOSeeker').  However, it maintains an in-memory buffer with the 
+contents of the file, rather than an actual on-disk file.  You can access
+the entire contents of this buffer at any time.  This can be quite useful
+for testing I\/O code, or for cases where existing APIs use I\/O, but you
+prefer a String representation.  You can create a 'MemoryBuffer' with a call
+to 'newMemoryBuffer'.
+
+Finally, there are pipes.  These pipes are analogous to the Unix
+pipes that are available from System.Posix, but don't require Unix and work
+only in Haskell.  When you create a pipe, you actually get two HVIO objects:
+a 'PipeReader' and a 'PipeWriter'.  You must use the 'PipeWriter' in one
+thread and the 'PipeReader' in another thread.  Data that's written to the
+'PipeWriter' will then be available for reading with the 'PipeReader'.  The
+pipes are implemented completely with existing Haskell threading primitives,
+and require no special operating system support.  Unlike Unix pipes, these
+pipes cannot be used across a fork().  Also unlike Unix pipes, these pipes
+are portable and interact well with Haskell threads.  A new pipe can be created
+with a call to 'newHVIOPipe'.
+
 -}
 
-module MissingH.HVIO(-- * Implementation Classes
+module MissingH.IO.HVIO(-- * Implementation Classes
                      HVIOGeneric(..), 
                      HVIOReader(..),
                      HVIOWriter(..),
@@ -40,8 +120,8 @@ module MissingH.HVIO(-- * Implementation Classes
                      -- * Standard Virtual IO features
                      -- | Note: Handle is a member of all classes by default.
                      StreamReader, newStreamReader,
-                     MemoryVIO, newMemoryVIO,
-                     PipeReader, PipeWriter, newPipe
+                     MemoryBuffer, newMemoryBuffer,
+                     PipeReader, PipeWriter, newHVIOPipe
                     )
 where
 
@@ -272,30 +352,30 @@ instance HVIOReader StreamReader where
 {- | Simulate true I\/O on a buffer.
 
 -}
-newtype MemoryVIO = MemoryVIO (VIOCloseSupport (Int, String))
+newtype MemoryBuffer = MemoryBuffer (VIOCloseSupport (Int, String))
 
-newMemoryVIO :: IO MemoryVIO
-newMemoryVIO = do ref <- newIORef (True, (0, ""))
-                  return (MemoryVIO ref)
+newMemoryBuffer :: IO MemoryBuffer
+newMemoryBuffer = do ref <- newIORef (True, (0, ""))
+                     return (MemoryBuffer ref)
 
-vrv (MemoryVIO x) = x
+vrv (MemoryBuffer x) = x
 
 -- | Grab the entire contents of the buffer as a string.
-getMemoryVIOBuffer :: MemoryVIO -> IO String
-getMemoryVIOBuffer h = do c <- vioc_get (vrv h)
-                          return (snd c)
+getMemoryBuffer :: MemoryBuffer -> IO String
+getMemoryBuffer h = do c <- vioc_get (vrv h)
+                       return (snd c)
 
-instance Show MemoryVIO where
-    show _ = "<MemoryVIO>"
+instance Show MemoryBuffer where
+    show _ = "<MemoryBuffer>"
 
-instance HVIOGeneric MemoryVIO where
+instance HVIOGeneric MemoryBuffer where
     vClose = vioc_close . vrv
     vIsEOF h = do vTestOpen h
                   c <- vioc_get (vrv h)
                   return ((length (snd c)) == (fst c))
     vIsOpen = vioc_isopen . vrv
 
-instance HVIOReader MemoryVIO where
+instance HVIOReader MemoryBuffer where
     vGetChar h = do vTestEOF h
                     c <- vioc_get (vrv h)
                     let retval = (snd c) !! (fst c)
@@ -308,14 +388,14 @@ instance HVIOReader MemoryVIO where
                         vClose h
                         return retval
 
-instance HVIOWriter MemoryVIO where
+instance HVIOWriter MemoryBuffer where
     vPutStr h s = do (pos, buf) <- vioc_get (vrv h)
                      let (pre, post) = splitAt pos buf
                      let newbuf = pre ++ s ++ (drop (length buf) post)
                      vioc_set (vrv h) (pos + (length buf), newbuf)
     vPutChar h c = vPutStr h [c]
 
-instance HVIOSeeker MemoryVIO where
+instance HVIOSeeker MemoryBuffer where
     vTell h = do v <- vioc_get (vrv h)
                  return . fromIntegral $ (fst v)
     vSeek h seekmode seekposp = 
@@ -334,12 +414,12 @@ instance HVIOSeeker MemoryVIO where
 -- Pipes
 ----------------------------------------------------------------------
 
-newPipe :: IO (PipeReader, PipeWriter)
-newPipe = do mv <- newEmptyMVar
-             readerref <- newIORef (True, mv)
-             let reader = PipeReader readerref
-             writerref <- newIORef (True, reader)
-             return (reader, PipeWriter writerref)
+newHVIOPipe :: IO (PipeReader, PipeWriter)
+newHVIOPipe = do mv <- newEmptyMVar
+                 readerref <- newIORef (True, mv)
+                 let reader = PipeReader readerref
+                 writerref <- newIORef (True, reader)
+                 return (reader, PipeWriter writerref)
 
 data PipeBit = PipeBit Char 
              | PipeEOF

-- 
haskell-testpack



More information about the Pkg-haskell-commits mailing list