-----------------------------------------------------------------------------
--
--                     Onions Network Streams Library
--
--             O N I O N S . I N S T R E A M S . L I N E B U F
--
--                                 S p e c
--
--     Copyright (C) 1997-1998  Regents of the University of California
--
--  Onions 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, with or without the single exception listed below;
--  either version 2, or (at your option) any later version.  Onions 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.
--  You should have received a copy of the GNU General Public License
--  distributed with Onions; see the file COPYING.  If not, write to the
--  Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
--  02111-1307, USA.
--
--  As a special exception, if other files instantiate generics from this
--  library, or you link this library with other files to produce an
--  executable, this library does not by itself cause the resulting
--  executable to be covered by the GNU General Public License.  This
--  exception does not however invalidate any other reasons why the
--  executable file might be covered by the GNU General Public License.
--
--  Created in 1997 by Roy T. Fielding
-----------------------------------------------------------------------------
--
--  The Line Buffered Input Stream is a filter that coalesces input data
--  into a complete line and removes the line terminator (CRLF, LF, or CR)
--  before passing the data downstream.
--

with Ada.Streams;
with Onions.Buckets; use Onions.Buckets;

package Onions.Instreams.Linebuf is

   type LB_Input_Stream is new Input_Stream with private;

   type LB_Input_Stream_Ptr is access all LB_Input_Stream;

   --------------------------------------------------------------------
   --            Dispatching Stream Control Operations               --
   --                                                                --
   --  If a dispatching method has an implementation that invokes    --
   --  another primitive method, then derived classes MUST override  --
   --  the dispatching method or be totally screwed, since Ada95     --
   --  only does dynamic invocation within classwide methods.        --
   --  Combine this with hidden implementation bodies and ... yes,   --
   --  you guessed it, all dispatching methods must be overridden    --
   --  by all derived types.  Who needs multiple inheritance when    --
   --  you can have zero inheritance at double the price?  *sigh*    --
   --------------------------------------------------------------------

   --  Free the storage associated with a stream object.
   --
   procedure Free (SP : in out LB_Input_Stream_Ptr);

   --  Close a stream object and propagate the close upstream.
   --
   procedure Close (Stream : in out LB_Input_Stream);

   --  Abort_Stream should only be used if a stream is interrupted
   --  by the user, or an error occurs that makes the whole stream bad.
   --  It forces the stream closed without a flush.
   --
   procedure Abort_Stream (Stream : in out LB_Input_Stream);

   --  Reset is like Close, but resets the stream to the state
   --  it would be in if it was just created.  It discards
   --  anything in its own buffers.
   --
   procedure Reset (Stream : in out LB_Input_Stream);

   --  Drain the stream by reading once from outbound and processing any
   --  unprocessed data as if it were the end-of-stream.
   --
   procedure Drain
      (Stream   : in out LB_Input_Stream;
       ItemList : out Bucket_List);

   ------------------------------------
   --  Ada.Streams Dispatching Read  --
   ------------------------------------

   --  Read obtains stream elements from Stream and places them into
   --  the components of Item until each component is filled or
   --  no elements remain on the stream or a complete line has been read.
   --  Last is set to the index of the last filled component of Item.
   --  This interface is defined by Ada.Streams for abstract stream
   --  operations.  We won't use it much because it forces a full data copy
   --  when filtering.
   --
   procedure Read
      (Stream : in out LB_Input_Stream;
       Item   : out Ada.Streams.Stream_Element_Array;
       Last   : out Ada.Streams.Stream_Element_Offset);

   ----------------------------------
   --  Data Processing Operations  --
   ----------------------------------

   --  Process does the magic necessary to read from the upstream object
   --  and move the data from the Unprocessed read queue to the Processed
   --  read queue.  In this case, it just waits for a full line of data and
   --  coalesces the line into a single bucket.  If Everything, then process
   --  the entire Unprocessed buffer as if it were the end-of-stream.
   --  Raises End_Error if end-of-stream is encountered and nothing has been
   --  processed, or Status_Error if the outbound stream is not connected.
   --
   procedure Process (Stream : in out LB_Input_Stream; Everything : Boolean);

private

   type LB_Input_Stream is new Input_Stream with record
      --  DoneList keeps track of data that has been looked at but is
      --  not yet a complete line.
      --
      DoneList : Bucket_List := null;

   end record;

end Onions.Instreams.Linebuf;