english
version "1.0"
identify "xyz"

#: Copyright (c) 1991-2005 by Wayne C. Gramlich.
#, All rights reserved.

module in_stream

#: The in_stream module implements input stream objects and their
#, associated operations.

define in_stream
    external


procedure address_get@in_stream
    takes
	in_stream in_stream
    returns address
    external in_stream__address_get

    #: This procedure will return the address of {in_stream}.



procedure character_get@in_stream
    takes
	in_stream in_stream
    returns character
    external in_stream__character_get

    #: this procedure will read one character from {in_stream} and return it.
    #, FIXME: This routine should have been called
    #, {character_read}@{in_stream} instead!!



procedure character_read@in_stream
    takes
	in_stream in_stream
    returns character

    #: This procedure will read on character from {in_stream} and return it.
    #, If an end-of-file condition is encountered, a character value of
    #, 0xffffffff is returned.


procedure character_match@in_stream
    takes
	in_stream in_stream
	match_character character
	error_stream out_stream
    returns logical

    #: This procedure will read the next character from {in_stream}
    #, and verify that it matches {match_character}.  If it matches,
    #, {false} is returned.  If it does not match, {true} is returned
    #, and an error message is printed to {error_stream}.  If {error_stream}
    #, is equal to ??@{out_stream}, the error message is suppressed.


procedure close@in_stream
    takes
	in_stream1 in_stream
    returns_nothing
    external in_stream__close

    #: This procedure will close {in_stream1}.  All subsequent operations
    #, on {in_stream1} will behave as if it is connected to /dev/null.



procedure contents_read@in_stream
    takes
	in_stream in_stream
	result string
    returns_nothing

    #: This procedure will read in the entire contents of {in_stream}
    #, and append it to {result}.  {close}@{in_stream}() should be
    #, called immediately afterwards.


procedure decimal_read@in_stream
    takes
	in_stream in_stream
	error_stream out_stream
    returns unsigned

    #: This procedure will read in a decimal number from {in_stream}
    #, an return the result.  If no decimal number is encounterd,
    #, an error message is output to {error_stream} and 0xffffffff
    #, is returned.  If {error_stream} is ??@{out_stream}, the
    #, error message is supressed


procedure end_of_line_read@in_stream
    takes
	in_stream in_stream
	error_stream out_stream
    returns_nothing

    #: This procedure will read an end-of-line.  If any extra characters
    #, are encoutnered, an error message is output to {error_stream}.
    #, If {error_stream} is ??@{out_stream}, the error message is supressed.


procedure xdescriptor_open@in_stream
    takes
	descriptor unsigned
    returns in_stream

    #: This procedure will return an {in_stream} object that is
    #, connect to {descriptor}.  If an error occures, ??@{in_stream}
    #, is returned.


procedure descriptor_open@in_stream
    takes
	descriptor unsigned
    returns in_stream
    external in_stream__descriptor_open

    #: This procedure will return an {in_stream} object that is
    #, connect to {descriptor}.  If an error occures, ??@{in_stream}
    #, is returned.



procedure eof_get@in_stream
    takes
	in_stream1 in_stream
    returns logical
    external in_stream__eof_get

    #: This procedure will return {logical@true} if there are no more
    #, characters to be read from {in_stream1}; otherwise, {logical@false}
    #, is returned.



procedure file_name_get@in_stream
    takes
	in_stream1 in_stream
    returns string
    external in_stream__file_name_get

    #: This procedure will return the file name associated with {in_stream1}.



procedure float_read@in_stream
    takes
	in_stream in_stream
    returns float
    external in_stream__float_read

    #: This procedure will read a {float} from {in_stream} and return it.
    #, The float should have been written unsing {float_write}@{out_stream}.
    


procedure hexadecimal_read@in_stream
    takes
	in_stream in_stream
	error_stream out_stream
	radix unsigned
    returns unsigned

    #: This procedure will read in a hexadecimal number from {in_stream}
    #, an return the result.  If no hexadecimal number is encounterd,
    #, an error message is output to {error_stream} and 0xffffffff
    #, is returned.  If {error_stream} is ??@{out_stream}, the
    #, error message is supressed


procedure identical@in_stream
    takes
	in_stream1 in_stream
	in_stream2 in_stream
    returns logical

    #: This procedure will return {true} if {in_stream1} and {in_stream2}
    #, refer to the identical {in_stream} object and {false} otherwise.


procedure is_open_get@in_stream
    takes
	in_stream1 in_stream
    returns logical
    external in_stream__is_open_get

    #: This procedure will return {logical@true} if {in_stream} is connected
    #, an open input stream.



procedure number_read@in_stream
    takes
	in_stream in_stream
	error_stream out_stream
	radix unsigned
    returns unsigned

    #: This procedure will read in a number of {radix} from {in_stream}
    #, an return the result.  If no number is encounterd,
    #, an error message is output to {error_stream} and 0xffffffff
    #, is returned.  If {error_stream} is ??@{out_stream}, the
    #, error message is supressed.


procedure line_read@in_stream
    takes
	in_stream in_stream
	line string
	keep_new_line logical
    returns logical

    #: This procedure will read the next line of text from {in_stream}
    #, and enter it into {line}.  If {keep_new_line} is {false}, the
    #, terminating new line character(s) are not appended to {line};
    #, otherwise, the terminating new line character(s) are appended
    #, in {line}.  Remember that the last line in the file may not be
    #, terminated by new-line character(s).  {true} is returned if
    #, at least one character has been read; otherwise, {false} is
    #, returned to indicate the end-of-file condition.


procedure open@in_stream
    takes
	file_name string
    returns in_stream
    external in_stream__open

    #: This procedure will open the file named {file_name} and return an
    #, associated {in_stream}.  If the file can not be opened, the returned
    #, {in_stream} object will behave as if it is connected to /dev/null.
    #FIXME: This should return ??@{in_stream} for an error!!!



procedure open_read@in_stream
    takes
	file_name string
    returns in_stream

    #: This procedure will open the file named {file_name} and
    #, return the corresponding {in_stream} object.  If the open
    #, does not succeed, ??@{in_stream} is returned.


procedure map@in_stream
    takes
	in_stream in_stream
    returns string

    #: This procedure will take the open file associated with {in_stream},
    #, map it into memory and return it as a string.


procedure next@in_stream
    takes
	in_stream1 in_stream
    returns character
    external in_stream__next

    #: This procedure will return the next character from {in_stream1}.
    #, At end-of-file, `\0' is returned.


procedure position_get@in_stream
    takes
	in_stream1 in_stream
    returns unsigned
    external in_stream__position_get

    #: This procedure will return the current character position of {in_stream}.


procedure peek@in_stream
    takes
	in_stream1 in_stream
    returns character
    external in_stream__peek

    #: This procedure will return the next character from {in_stream} without
    #, actually reading it.  At end-of-file, `\0' is returned.  Multiple
    #, consequtive calls to this routine, always return the same result.
    #, FIXME: At end-of-file 0xffffffff should be returned!!!



procedure print@in_stream
    takes
	in_stream in_stream
	out_stream out_stream
    returns_nothing
    external in_stream__print

    #: This procedure will print {in_stream} onto {out_stream}.



procedure string_read@in_stream
    takes
	in_stream in_stream
	string string
	error_stream out_stream
    returns string

    #: This procedure will read in a string from {in_stream}
    #, and store it into {string}.  A string starts with either
    #, a single quote or a double quote.  If an end-of-line or
    #, end-of-file is encountered before the the closing quote
    #, is encountered, an error message is output to {error_stream}.
    #, Similarly, if a begining quote is not encountered, an error
    #, message is generated.  The error message is supressed if
    #, {error_stream} is equal to ??@{out_stream}.  If {symbol}
    #, is ??@{string}, a new string is allocated and the symbol
    #, is stored in there and returned.


procedure symbol_read@in_stream
    takes
	in_stream in_stream
	symbol string
	error_stream out_stream
    returns string

    #: This procedure will read in a symbol from {in_stream}
    #, and store it into {symbol}.  A symbol is just a sequence
    #, of non white space characters.  If an end-of-line or
    #, end-of-file is encountered before the any symbol, an error
    #, message is output to {error_stream}.  The error message
    #, is supressed if {error_stream} is equal to ??@{out_stream}.
    #, If {symbol} is ??@{string}, a new string is allocated and
    #, the symbol is stored in there and returned.


procedure xml_attribute_read@in_stream
    takes
	in_stream in_stream
	attribute_name string
	attribute_value string
    returns logical

    #: This procedure will read in an XML attribute from {in_stream}
    #, and append the attribute name to {attribute_name} and the
    #, attribute value in {attribute_value}.


procedure xml_space_skip@in_stream
    takes
	in_stream in_stream
    returns_nothing

    #: This procedure will read over any spaces, tabs and new line characters
    #, until a printing character is encountered.


procedure xml_tag_read@in_stream
    takes
	in_stream in_stream
	tag_name string
    returns logical

    #: This procedure will in an XML tag of the form "<{tag_name}" from
    #, {in_stream} and append the tag name to {tag_name}.


procedure xml_tag_end@in_stream
    takes
	in_stream in_stream
	single_tag logical
    returns logical

    #: This procedure will read in the end of a tag from {in_stream}.
    #, If {single_tag} is {true}, the end of the tag must be preceeded
    #, by a slash.  {true} is returned if there are any problems and
    #, {false} otherwise.


procedure xml_tag_match@in_stream
    takes
	in_stream in_stream
	tag_name string
    returns logical

    #: This procedure will ensure that the next XML tag matches {tag_name}.
    #, If it matches, {false} is returned; otherwise, {true} is returned.