--
-- Copyright (c) 2012 Kevin Wellwood
-- All rights reserved.
--
-- This source code is distributed under the Modified BSD License. For terms and
-- conditions, see license.txt.
--
with Ada.Streams; use Ada.Streams;
with Objects; use Objects;
with Resources; use Resources;
package Resources.Archives is
-- An Archive is a data file containing individually addressable files. The
-- Archive class should be subclassed for each archive file format supported
-- by the application.
type Archive is abstract new Limited_Object with private;
type A_Archive is access all Archive'Class;
-- Loads an Archive into memory from a resource file. The resource can be
-- unloaded independently of the Archive after calling this function.
function Load_Archive( resource : not null A_Resource_File ) return A_Archive;
pragma Postcondition( Load_Archive'Result /= null );
-- Returns true if 'filename' exists in the Archive.
function Exists( this : access Archive;
filename : String ) return Boolean is abstract;
-- Reads 'filename' from the Archive and returns it as a raw in-memory
-- buffer. The caller takes ownership of the returned buffer; closing the
-- Archive does not affect it. An exception is raised on error.
function Load_Raw( this : access Archive;
filename : String ) return access Stream_Element_Array is abstract;
-- Reads 'filename' from the Archive as a resource file. The caller takes
-- ownership of the returned object; closing the archive does not affect it.
-- An exception will be raised on error.
function Load_Resource( this : access Archive;
filename : String ) return A_Resource_File is abstract;
-- Deletes the Archive.
procedure Delete( this : in out A_Archive );
pragma Postcondition( this = null );
-- Raised if an archive or a file in an archive can't be found.
FILE_NOT_FOUND : exception;
-- Raised if a read error occurs while attempting to load an archive. The
-- archive file is probably corrupt.
READ_ERROR : exception;
-- Raised if the file extension of an archive is not supported.
ARCHIVE_FORMAT_ERROR : exception;
private
type Archive is abstract new Limited_Object with
record
path : Unbounded_String;
end record;
-- 'path' is the absolute path of the archive.
procedure Construct( this : access Archive; path : String );
----------------------------------------------------------------------------
-- Prototype for a function that loads an archive from a Resource_File.
type A_Archive_Loader is
access function( resource : not null A_Resource_File ) return A_Archive;
-- Registers an archive file format by file extension. 'ext' is not case
-- sensitive, should not contain a leading dot character, and may only be
-- registered once. This procedure should be called at elaboration time by
-- child packages that subclass Archive.
procedure Register_Format( ext : String; loader : not null A_Archive_Loader );
end Resources.Archives;