-----------------------------------------------------------------------------
--
--         libwww-ada95 : A World Wide Web client library for Ada95
--
--            O N I O N S . I N S T R E A M S . H T M L _ D I R
--
--                                 S p e c
--
--     Copyright (C) 1997-1998  Regents of the University of California
--
--  libwww-ada95 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.  libwww-ada95 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 libwww-ada95; 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 and Yuzo Kanomata
-----------------------------------------------------------------------------
--
--  The HTML Directory Stream is an input stream filter that takes a
--  stream of filenames (assumed to be generated by Onions.Instreams.Dir),
--  gets the file info for each one via Onions.OS.Stat, and outputs an
--  HTML formatted listing similar to that seen on a modern browser.
--
--  To use, push a new HTML_Dir_Stream object onto a just Opened
--  Dir_Input_Stream object and read until End_Error is raised.
--
--  You may be wondering why this is in the WWW directory instead of
--  in the Onions directory.  Well, it's because Onions is intended to
--  be an application-independent library, but this functionality is very
--  much a WWW thing.  Then why call it Onions.Instreams.HTML_Dir?
--  Because you can't just inherit functionality in Ada95 -- you need
--  to be a child package of the parent class's package so that you can
--  actually use the variables and state that have been inherited.
--

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

package Onions.Instreams.HTML_Dir is

   type HTML_Dir_Stream is new Input_Stream with private;

   type HTML_Dir_Stream_Ptr is access HTML_Dir_Stream;

   ---------------------------------------------
   --  Dispatching Stream Control Operations  --
   ---------------------------------------------

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

   --  Close a stream object and propagate the close upstream.
   --
   procedure Close (Stream : in out HTML_Dir_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 HTML_Dir_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 HTML_Dir_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 HTML_Dir_Stream;
       ItemList : out Bucket_List);

   ------------------------------------------
   --  Ada.Streams Dispatching Operations  --
   ------------------------------------------

   --  Read obtains stream elements from Stream and places them into
   --  the components of Item until either each component is filled or
   --  no elements remain on the stream.  Last is set to the index of
   --  the last component of Item that was filled.  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 HTML_Dir_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, there is no magic.  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 HTML_Dir_Stream;
       Everything : Boolean);

   --  Unprocess undoes the magic of Process and UnReads the data to
   --  the upstream object.
   --
   procedure Unprocess (Stream : in out HTML_Dir_Stream);

private

   type HTML_Dir_Stream is new Input_Stream with record

      --  Keep totals so that we can print a summary
      --
      Total_Files : Natural := 0;
      Total_Bytes : Natural := 0;

      --  Remember if we have seen the end-of-stream and ended output
      --
      Done_Trailer : Boolean := False;

   end record;

end Onions.Instreams.HTML_Dir;