--
-- Author:  Robert C. Shock,  Dept of CS & CEG   Wright State University
-- In cooperation with:  WRDC/ELED WPAFB   Dayton, OH
--
-- Source: io_unit_.a
--
-- ABSTRACT OVERVIEW: package io_unit
--
-- << Purpose >>
-- The package io_unit provides the mechanism to treat independent of a machine these terminators: end_file, end_page, end_line.
-- Each terminator is assigned a unique character and the 'put' procedure below executes the corresponding function associated with the terminator character; Example: put ( the_end_line_character ) outputs "text_io.new_line".
--
-- << Input stream >>
-- The input stream has two components: user_stack and input_filter ( defined by G. Booch ) The input stream has a logical/hypothetical pointer called cursor that identifies exactly one character of the input stream. The rules that govern the cursor are below. 
--   DEFINE CURSOR:  the cursor points to
--      the top of the user_stack when the user_stack is not empty.
--      the next character of the input_filter when the user_stack is empty and
--           not at end of the standard input
--      the_end_line_character otherwise
--
--   ACCESS CURSOR:
--  The function 'next_character_is' returns the cursor value and its logical action is described by: 
--     if the user stack /= empty, then return the top and then pop the stack
--     elsif not at end of the standard input then
--            return the next character of the input stream 
--     else return 'the_end_file_character'
--           
--   CONTROL PAGE TERMINATOR:
--   The procedure 'set_process_page_terminator' will pass 'the_end_page_character' to the input stream, while 'set_bypass_page_terminator' does not pass 'the_end_page_character' 
-- 
--  ASSUMPTION: the package body code call 'set_bypass_page_terminator' 
--
--
-- << user_stack >>
-- The user_stack is bounded by 'the_number_of_push_back_character'. The procedure 'push_back' pushes a character on the user_stack; when the stack is full 'push_back' removes the last element of the stack and place the character on the top of the stack. 
-- Suppose the bound is three and five consecutive calls of 'push_back' are made. Then the last three characters are stored, the first two pushed are lost.
--

package io_unit is 

-- input mechanism

-- define end text terminators

the_end_file_character: constant character := ascii.eot;
the_end_page_character: constant character := ascii.ff;
the_end_line_character: constant character := ascii.lf;


the_number_of_push_back_characters: constant natural := 4;


function next_character_is return character;
-- Effect:  
--     if the user stack /= empty, then return the top and then pop the stack
--     elsif not at end of the standard input then
--            return the next character of the input stream 
--     else return 'the_end_file_character'
--  Note: if 'set_the_bypass_page_terminator' is set, then Ada logical page terminator is not passed to the input stream, that is, the associated character, 'the_end_page_character' is not passed to the input stream 


function next_line_is return string;
-- Effect: return the slice:: current input character .. (including) the_end_line_character when not at end of file 
--   otherwise return the string  ( 'the_end_page_character', 'the_end_file_character' ) on the first call when at the end of file and return the string ( 'the_end_file_character' ) on all other calls
--  Note: if 'set_the_bypass_page_terminator' is set, then Ada logical page terminator is not passed to the input stream, that is, the associated character, 'the_end_page_character' is not passed to the input stream 




-- CONSTRUCTORS 

procedure clear;
-- Effect: sets all internal states to a begin state; the user_stack is empty


procedure set_bypass_the_page_terminator;
-- Effect: does not pass the logical page terminator to the input stream 


procedure set_process_the_page_terminator;
-- Effect: does pass the logical page terminator to the input stream 


procedure get ( the_character: out character );
-- Effect: assigns the value returned from 'next_character_is' 


procedure push_back ( the_character: in character );
-- Effect: push 'the_character' onto the user_stack by the rules stated above 

-- output mechanism

procedure put ( the_character: in character );
-- Effect: for each terminator character in the string the associated function is executed while text_io.put is used to print ( put ) all other characters.
-- Note, the action of put ( 'the_end_file_character ') is null, that is no terminator is printed;


procedure put ( the_string: in string );
-- Effect: for each terminator character in the string the associated function is executed while text_io.put is used to print ( put ) all other characters.


   -- ITERATOR: passive over characters
-- passes to process once each character of the input stream; note the last character passed is 'the_end_file_character'

generic

   with procedure process ( the_character: in character; continue: out boolean );
   
procedure iterate_input_stream;



   -- ITERATOR: passive over lines 
-- passes once to the process each line defined by 'next_line_is' 

generic

   with procedure process ( the_line: in string; continue: out boolean );
   
procedure iterate_input_stream_with_lines;

end io_unit;