1. -- 
  2. -- Copyright (c) 2012 Kevin Wellwood 
  3. -- All rights reserved. 
  4. -- 
  5. -- This source code is distributed under the Modified BSD License. For terms and 
  6. -- conditions, see license.txt. 
  7. -- 
  8.  
  9. with Ada.Streams;                       use Ada.Streams; 
  10. with Objects;                           use Objects; 
  11. with Resources;                         use Resources; 
  12.  
  13. package Resources.Archives is 
  14.  
  15.     -- An Archive is a data file containing individually addressable files. The 
  16.     -- Archive class should be subclassed for each archive file format supported 
  17.     -- by the application. 
  18.     type Archive is abstract new Limited_Object with private; 
  19.     type A_Archive is access all Archive'Class; 
  20.  
  21.     -- Loads an Archive into memory from a resource file. The resource can be 
  22.     -- unloaded independently of the Archive after calling this function. 
  23.     function Load_Archive( resource : not null A_Resource_File ) return A_Archive; 
  24.     pragma Postcondition( Load_Archive'Result /= null ); 
  25.  
  26.     -- Returns true if 'filename' exists in the Archive. 
  27.     function Exists( this     : access Archive; 
  28.                      filename : String ) return Boolean is abstract; 
  29.  
  30.     -- Reads 'filename' from the Archive and returns it as a raw in-memory 
  31.     -- buffer. The caller takes ownership of the returned buffer; closing the 
  32.     -- Archive does not affect it. An exception is raised on error. 
  33.     function Load_Raw( this     : access Archive; 
  34.                        filename : String ) return access Stream_Element_Array is abstract; 
  35.  
  36.     -- Reads 'filename' from the Archive as a resource file. The caller takes 
  37.     -- ownership of the returned object; closing the archive does not affect it. 
  38.     -- An exception will be raised on error. 
  39.     function Load_Resource( this     : access Archive; 
  40.                             filename : String ) return A_Resource_File is abstract; 
  41.  
  42.     -- Deletes the Archive. 
  43.     procedure Delete( this : in out A_Archive ); 
  44.     pragma Postcondition( this = null ); 
  45.  
  46.     -- Raised if an archive or a file in an archive can't be found. 
  47.     FILE_NOT_FOUND : exception; 
  48.  
  49.     -- Raised if a read error occurs while attempting to load an archive. The 
  50.     -- archive file is probably corrupt. 
  51.     READ_ERROR : exception; 
  52.  
  53.     -- Raised if the file extension of an archive is not supported. 
  54.     ARCHIVE_FORMAT_ERROR : exception; 
  55.  
  56. private 
  57.  
  58.     type Archive is abstract new Limited_Object with 
  59.         record 
  60.             path : Unbounded_String; 
  61.         end record; 
  62.  
  63.     -- 'path' is the absolute path of the archive. 
  64.     procedure Construct( this : access Archive; path : String ); 
  65.  
  66.     ---------------------------------------------------------------------------- 
  67.  
  68.     -- Prototype for a function that loads an archive from a Resource_File. 
  69.     type A_Archive_Loader is 
  70.         access function( resource : not null A_Resource_File ) return A_Archive; 
  71.  
  72.     -- Registers an archive file format by file extension. 'ext' is not case 
  73.     -- sensitive, should not contain a leading dot character, and may only be 
  74.     -- registered once. This procedure should be called at elaboration time by 
  75.     -- child packages that subclass Archive. 
  76.     procedure Register_Format( ext : String; loader : not null A_Archive_Loader ); 
  77.  
  78. end Resources.Archives;