;;
;; endian-port documentation for the Chicken Scheme module system.
;;
;; Copyright 2005-2008 Ivan Raikov and the Georgia Institute of Technology
;;
;; This program is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful, but
;; WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;; General Public License for more details.
;;
;; A full copy of the GPL license can be found at
;; <http://www.gnu.org/licenses/>.
;;

(use eggdoc)

(define doc
  `((eggdoc:begin
     (name "endian-port")
     (description "An I/O port that supports different endian formats.")
     (author (url "http://chicken.wiki.br/ivan raikov" "Ivan Raikov"))
     (author (url "http://ecloud.org" "Ported to chicken 4 by Shawn Rutledge"))

     (history 
      (version "3.0" "Ported to chicken 4, using endian-blob rather than the previously-included C implementation")
      (version "2.3" "Small updates to license and copyright information")
      (version "2.2" "Fixed include of ansidecl.h")
      (version "2.1" "Build script updated for better cross-platform compatibility")
      (version "2.0" "New version to force rebuilding of egg")
      (version "1.9" "Bug fix in the setup script")
      (version "1.8" "eggdoc documentation fix")
      (version "1.7" "License upgrade to GPL v3")
      (version "1.6" "Bug fix in endian-port-write-bit-vector")
      (version "1.5" "Minor updates to the setup script")
      (version "1.4" "Bug fix in the setup script")
      (version "1.3" "Minor updates to the egg configuration files")
      (version "1.2" "Fix to properly read byte vectors")
      (version "1.1" "Fix to raise an exception on I/O error [thanks to Kon Lovett]")
      (version "1.0" "Initial release"))

     (requires (url "iset.html" "iset"))

     (usage "(require-extension endian-port)")

     (download "endian-port.egg")

     (documentation
      (p "endian-port is a module that supports reading and writing of
integers, IEEE floating-point numbers, and byte vectors while taking
into account byte order.  It is based on routines from the C++ advanced
I/O library and TIFF reader written by Oleg Kiselyov.")

       (subsection "Endian port data structures"

           (record "(define-record endian-port fileno filename byte-order)"
		   (p "A record that represents an endian port. " 
		       "Field " (tt "fileno") " is the file handle for that port. " 
		       "Field " (tt "filename") " is the file name for that port. " 
		       "Field " (tt "byte-order") " can be one of " (tt "MSB") 
		       " or " (tt "LSB") ". " 
		       "The type " (tt "byte-order") " is defined in the C module " (tt "endian-lowio") ".")))

       (subsection "Endian port routines"
       
		   (procedure "open-endian-port:: MODE * FILENAME -> ENDIAN-PORT"
			      (p "Opens an endian port to the
specified file. Mode can be one of " (tt "'read") " or " (tt
"'write") ". " "In write mode, the file is created if it doesn't exist,
otherwise the new data is appended to its end. The default endianness
of the newly created endian port is MSB."))

		   (procedure "port->endian-port:: PORT -> ENDIAN-PORT"
			      (p "Creates an endian port to the file
specified by the given port. The default endianness of the newly
created endian port is MSB."))

		   (procedure "close-endian-port:: ENDIAN-PORT -> UNDEFINED"
			      (p "Closes the endian port."))


		   (procedure "endian-port-set-bigendian!:: EPORT -> UNDEFINED"
			      (p "Sets the endianness of the given endian port to MSB."))
		   
		   (procedure "endian-port-set-littleendian!:: EPORT -> UNDEFINED"
			      (p "Sets the endianness of the given endian port to LSB."))
		   
		   (procedure "endian-port-setpos:: EPORT * INTEGER [* WHENCE] -> UNDEFINED"
			      (p "Sets the file position of the given
endian port to the specified position. The optional argument " (tt
"WHENCE") " is one of " (tt "seek/set") ", " (tt "seek/cur") ", " (tt "seek/end") ". The default is
" (tt "seek/set") " (current position)."))

		   (procedure "endian-port-pos:: EPORT  -> INTEGER"
			      (p "Returns the current file position of
the given endian port, relative to the beginning of the file."))

		   (procedure "endian-port-eof?:: EPORT  -> BOOLEAN"
			      (p "Returns " (tt "true") " if the
current file position of the given endian port is at the end of the
file, " (tt "false") " otherwise"))

		   (subsubsection 
		    "Routines for reading"

		    (procedure "endian-port-read-uint1:: EPORT [* BYTE-ORDER] -> UINTEGER"
			       (p "Reads an unsigned integer of size 1 byte. Optional argument "
				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))
		    
		    (procedure "endian-port-read-uint2:: EPORT [* BYTE-ORDER] -> UINTEGER"
			       (p "Reads an unsigned integer of size 2 bytes. Optional argument "
				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))
		    
		    (procedure "endian-port-read-uint4:: EPORT [* BYTE-ORDER] -> UINTEGER"
			       (p "Reads an unsigned integer of size 4 bytes. Optional argument "
				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))

		    (procedure "endian-port-read-int1:: EPORT [* BYTE-ORDER] -> INTEGER"
			       (p "Reads a signed integer of size 1 byte. Optional argument "
				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))
		    
		    (procedure "endian-port-read-int2:: EPORT [* BYTE-ORDER] -> INTEGER"
			       (p "Reads a signed integer of size 2 bytes. Optional argument "
				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))
		    
		    (procedure "endian-port-read-int4:: EPORT [* BYTE-ORDER] -> INTEGER"
			       (p "Reads a signed integer of size 4 bytes. Optional argument "
				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))

;		    (procedure "endian-port-read-int8:: EPORT [* BYTE-ORDER] -> UINTEGER"
;			       (p "Reads an unsigned integer of size 8 bytes. Optional argument "
;				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
;				  "If byte order is not specified, "
;				  "the procedure uses the byte order setting of the given endian port."))

                    (procedure "endian-port-read-ieee-float32:: EPORT [* BYTE-ORDER] -> UINTEGER"
			      (p "Reads an IEEE 754 single precision floating-point number. "
				 "Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
				 " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))

		   (procedure "endian-port-read-ieee-float64:: EPORT [* BYTE-ORDER] -> UINTEGER"
			      (p "Reads an IEEE 754 double precision floating-point number. "
				 "Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
				 " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))

		   (procedure "endian-port-read-bit-vector:: PORT * SIZE (in bits) [* BYTE-ORDER] -> BIT-VECTOR"
			      (p "Reads a bit vector of the specified size (in bits) "
				 "and returns an iset bit vector (see module " (url "iset.html" "iset") "). "
				 "Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
				 " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port."))

		   (procedure "endian-port-read-byte-vector:: PORT * SIZE [* BYTE-ORDER]  -> BYTE-VECTOR"
			      (p "Reads a byte vector of the specified size "
				 "and returns a Scheme blob object. Optional argument "
				  (tt "BYTE-ORDER") " is one of " (tt "MSB") " or " (tt "LSB") ". " 
				  "If byte order is not specified, "
				  "the procedure uses the byte order setting of the given endian port.")))

		   (subsubsection "Routines for writing"
				  (procedure "endian-port-write-uint1:: EPORT * WORD [* BYTE-ORDER] -> UINTEGER"
					     (p "Writes an unsigned integer of size 1 byte. "
						"Returns the number of bytes written (always 1). "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))

				  (procedure "endian-port-write-uint2:: EPORT * WORD [* BYTE-ORDER] -> UINTEGER"
					     (p "Writes an unsigned integer of size 2 bytes. "
						"Returns the number of bytes written (always 2). "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))


				  (procedure "endian-port-write-uint4:: EPORT * WORD [* BYTE-ORDER] -> UINTEGER"
					     (p "Writes an unsigned integer of size 4 bytes. "
						"Returns the number of bytes written (always 4). "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))

				  (procedure "endian-port-write-int1:: EPORT * WORD [* BYTE-ORDER] -> INTEGER"
					     (p "Writes a signed integer of size 1 byte. "
						"Returns the number of bytes written (always 1). "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))

				  (procedure "endian-port-write-int2:: EPORT * WORD [* BYTE-ORDER] -> INTEGER"
					     (p "Writes a signed integer of size 2 bytes. "
						"Returns the number of bytes written (always 2). "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))


				  (procedure "endian-port-write-int4:: EPORT * WORD [* BYTE-ORDER] -> INTEGER"
					     (p "Writes a signed integer of size 4 bytes. "
						"Returns the number of bytes written (always 4). "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))

;				  (procedure "endian-port-write-int8:: EPORT * WORD [* BYTE-ORDER] -> UINTEGER"
;					     (p "Writes an unsigned integer of size 8 bytes. "
;						"Returns the number of bytes written (always 8). "
;						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
;						" or " (tt "LSB") ". " 
;						"If byte order is not specified, "
;						"the procedure uses the byte order setting of the given endian port."))

				  (procedure "endian-port-write-ieee-float32:: EPORT * WORD [* BYTE-ORDER] -> UINTEGER"
					     (p "Writes an IEEE 754 single precision floating-point number. "
						"Returns the number of bytes written (always 4) bytes. "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))

				  (procedure "endian-port-write-ieee-float64:: EPORT * WORD [* BYTE-ORDER] -> UINTEGER"
					     (p "Writes an IEEE 754 double precision floating-point number. "
						"Returns the number of bytes written (always 8) bytes. "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))

				  (procedure "endian-port-write-byte-vector:: EPORT * BYTE-VECTOR [* BYTE-ORDER] -> UINTEGER"
					     (p "Writes the given byte vector and returns the number of bytes written. "
						"The argument must be a blob, u8vector or endian-blob. "
						"Optional argument " (tt "BYTE-ORDER") " is one of " (tt "MSB") 
						" or " (tt "LSB") ". " 
						"If byte order is not specified, "
						"the procedure uses the byte order setting of the given endian port."))

				  (procedure "endian-port-write-bit-vector:: EPORT * BIT-VECTOR [* BIT-ORDER] -> UINTEGER"
					     ((p "Writes the given bit vector and returns the number of bytes written. "
						 "The argument must be a bit vector as defined in the " 
						 (url "iset.html" "iset") " module. "
						 "Optional argument " (tt "BIT-ORDER") " is one of " 
						 (tt "MSB") " or "  (tt "LSB") ". "
						 "If bit order is not specified, the procedure uses "
						 "the byte order setting of the given endian port.")
					      (p "Note that here the \"byte order\" type is "
						 "interpreted as bit order: the order argument specifies that the bits "
						 "are ordered in MSB or LSB order, not the bytes that comprise the bit "
						 "vector."))))))

     (examples)

     (license
      "Copyright 2005-2008 Ivan Raikov and the Georgia Institute of Technology

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>."))))

(if (eggdoc->html doc) (void))