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 Allegro.Bitmaps;                   use Allegro.Bitmaps; 
  11. with Allegro.Files;                     use Allegro.Files; 
  12. with Objects;                           use Objects; 
  13. with Resources;                         use Resources; 
  14.  
  15. private with Ada.Strings.Unbounded; 
  16.  
  17. package Archives is 
  18.  
  19.     -- An Archive is a data file containing individually addressable files. The 
  20.     -- Archive class should be subclassed for each archive file format supported 
  21.     -- by the application. 
  22.     type Archive is abstract new Limited_Object with private; 
  23.     type A_Archive is access all Archive'Class; 
  24.  
  25.     -- Loads an Archive into memory. An exception is raised on error. 
  26.     function Load_Archive( path : String ) return A_Archive; 
  27.     pragma Postcondition( Load_Archive'Result /= null ); 
  28.  
  29.     -- Loads an Archive into memory from a resource file. The resource can be 
  30.     -- unloaded independently of the Archive after calling this function. 
  31.     function Load_Archive( resource : not null A_Resource_File ) return A_Archive; 
  32.     pragma Postcondition( Load_Archive'Result /= null ); 
  33.  
  34.     -- Returns true if 'filename' exists in the Archive. 
  35.     function Exists( this     : access Archive; 
  36.                      filename : String ) return Boolean is abstract; 
  37.  
  38.     -- Reads 'filename' from the Archive and opens it as an Allegro bitmap. The 
  39.     -- caller takes ownership of the returned bitmap; closing the archive does 
  40.     -- not affect it. An exception is raised on error. 
  41.     function Load_Bitmap( this     : access Archive; 
  42.                           filename : String ) return A_Bitmap is abstract; 
  43.  
  44.     -- Reads 'filename' from the Archive and opens it as an in-memory packfile. 
  45.     -- The caller takes ownership of the returned packfile; closing the archive 
  46.     -- does not affect it. An exception is raised on error. 
  47.     function Load_Packfile( this     : access Archive; 
  48.                             filename : String ) return A_Packfile is abstract; 
  49.  
  50.     -- Reads 'filename' from the Archive and returns it as a raw in-memory 
  51.     -- buffer. The caller takes ownership of the returned buffer; closing the 
  52.     -- Archive does not affect it. An exception is raised on error. 
  53.     function Load_Raw( this     : access Archive; 
  54.                        filename : String ) return access Stream_Element_Array is abstract; 
  55.  
  56.     -- Deletes the Archive. 
  57.     procedure Delete( this : in out A_Archive ); 
  58.     pragma Postcondition( this = null ); 
  59.  
  60.     -- Raised if an archive or a file in an archive can't be found. 
  61.     FILE_NOT_FOUND : exception; 
  62.  
  63.     -- Raised if a read error occurs while attempting to load an archive. The 
  64.     -- archive file is probably corrupt. 
  65.     READ_ERROR : exception; 
  66.  
  67.     -- Raised if the file extension of an archive is not supported. 
  68.     ARCHIVE_FORMAT_ERROR : exception; 
  69.  
  70. private 
  71.  
  72.     use Ada.Strings.Unbounded; 
  73.  
  74.     type Archive is abstract new Limited_Object with 
  75.         record 
  76.             path : Unbounded_String; 
  77.         end record; 
  78.  
  79.     -- 'path' is the absolute path of the archive. 
  80.     procedure Construct( this : access Archive; path : String ); 
  81.  
  82.     ---------------------------------------------------------------------------- 
  83.  
  84.     -- Prototype for a function that loads an archive from a physical path. 
  85.     type A_Path_Loader is 
  86.         access function( path : String ) return A_Archive; 
  87.  
  88.     -- Prototype for a function that loads an archive from a Resource_File. 
  89.     type A_Resource_Loader is 
  90.         access function( resource : not null A_Resource_File ) return A_Archive; 
  91.  
  92.     -- Registers an archive file format by file extension. 'ext' is not case 
  93.     -- sensitive, should not contain a leading dot character, and may only be 
  94.     -- registered once. This procedure should be called at elaboration time by 
  95.     -- child packages that subclass Archive. 
  96.     procedure Register_Format( ext        : String; 
  97.                                pathLoader : not null A_Path_Loader; 
  98.                                resLoader  : not null A_Resource_Loader ); 
  99.  
  100. end Archives;