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


-- | Pure Haskell implementation of PGM image format
--   
--   Reads and writes 8 and 16 bit PGM images, loading them into Haskell as
--   arrays.
@package pgm
@version 0.1


-- | <a>Graphics.Pgm</a> is a pure Haskell library to read and write PGM
--   images. It properly supports both 8 bit and 16 bit pixels, and
--   multiple PGMs per file. The PGM is the lowest common denominator of
--   useful image file formats. It consists of a header of the form
--   
--   <pre>
--   P5 width height maxVal
--   </pre>
--   
--   followed by a single whitespace charater, usually a newline, where
--   <tt>width</tt>, <tt>height</tt>, and <tt>maxVal</tt> are positive
--   integers consisting of digits only giving the number of columns,
--   number of rows, and the highest grey level in the image to follow.
--   
--   If <tt>maxVal</tt> &lt; 256, then the format uses 1 byte per pixel;
--   otherwise it uses 2. The routines in this library properly handle
--   both, including automatically determining which to write when writing
--   an array to disk.
--   
--   The header can also contain comments, starting with <tt>#</tt> on a
--   new line, and continuing to the end of the line. These are read out
--   and returned as a String with newlines kept intact (except for the
--   last newline of the last comment line, which is removed). Comments
--   from anywhere between the header fields are concatenated into the same
--   document. <a>pgmToArray</a> ignores comments;
--   <a>pgmToArrayWithComments</a> reads them.
--   
--   After the header, the pixel data is written in big-endian binary form,
--   most significant byte first for 16 bit pixels. The pixels are a single
--   row-major raster through the image.
--   
--   To put multiple PGMs in a file, append them. This module allows you to
--   put white space between them, though this might choke other
--   implementations.
--   
--   All arrays returned by this library from PGMs have pixel type
--   <a>Int</a>, since this is simply more useful for most purposes. If you
--   want to write a PGM back out, you must first coerce your pixel type to
--   <a>Word16</a>! There are too many possibile ways of handling negative
--   values, larger depths, or other things beyond the comprehension of
--   <a>Word16</a> to handle with a simple wrapper function. If you know
--   you have positive values less than 2^16, then you can coerce an array
--   <tt>arr</tt> to <a>Word16</a> with
--   
--   <pre>
--   amap (fromIntegral :: Int -&gt; Word16) arr
--   </pre>
--   
--   The array's indices (of the form (row,column)) start at (0,0) and run
--   to (<tt>height</tt>-1,<tt>width</tt>-1).
module Graphics.Pgm

-- | Parse the first (and possible only) PGM in a <a>ByteString</a> into an
--   array. If the parsing succeeds, you will still need to match on the
--   <a>Right</a> constructor to get the array.
pgmToArray :: (Integral a, IArray UArray a) => ByteString -> Either ParseError (UArray (Int, Int) a)

-- | Precisely the same as <a>pgmToArray</a>, but this time fetches all the
--   PGMs in the file, and returns them as a list of arrays.
pgmsToArrays :: (Integral a, IArray UArray a) => ByteString -> Either ParseError [UArray (Int, Int) a]

-- | The same as <a>pgmToArray</a>, but taking also returning the comments
--   in the PGM file as a String.
pgmToArrayWithComments :: (Integral a, IArray UArray a) => ByteString -> Either ParseError (UArray (Int, Int) a, String)

-- | Same as <a>pgmsToArrays</a>, but again returning comments.
pgmsToArraysWithComments :: (Integral a, IArray UArray a) => ByteString -> Either ParseError [(UArray (Int, Int) a, String)]

-- | Precisely the same as <a>arrayToPgm</a>, but takes a <a>String</a> to
--   encode into the file header as a comment after the magic number but
--   before the width field.
arrayToPgmWithComment :: (IArray m Word16) => m (Int, Int) Word16 -> String -> ByteString

-- | A wrapper around <a>pgmsFromHandle</a> which also opens the file to
--   read from.
pgmsFromFile :: String -> IO (Either ParseError [UArray (Int, Int) Int])

-- | Parse all PGMs in the contents of a handle, and return them as a list
--   of arrays.
pgmsFromHandle :: Handle -> IO (Either ParseError [UArray (Int, Int) Int])

-- | Takes an array (which must already be coerced to have element type
--   <a>Word16</a>) and produces a <a>ByteString</a> encoding that array as
--   a PGM.
arrayToPgm :: (IArray m Word16) => m (Int, Int) Word16 -> ByteString

-- | A wrapper around <a>arrayToHandle</a> which opens the file to write
--   to, then closes it afterwards.
arrayToFile :: (IArray m Word16) => String -> m (Int, Int) Word16 -> IO ()

-- | Write a single array to a given handle.
arrayToHandle :: (IArray m Word16) => Handle -> m (Int, Int) Word16 -> IO ()

-- | Writes a list of arrays to a given handle. Note that most
--   implementations of PGM will ignore all but the first when they read
--   this file.
arraysToHandle :: (IArray m Word16) => Handle -> [m (Int, Int) Word16] -> IO ()

-- | A wrapper around <a>arraysToHandle</a> which opens and closes the file
--   to write to.
arraysToFile :: (IArray m Word16) => String -> [m (Int, Int) Word16] -> IO ()