archive.core

class Archive(T, Filter = NullArchiveFilter);

The common template for all archives. Each archive format is implemented as a Policy class which supplies necessary types and methods specific to that format. Reference this class to find the methods available to all archives, but use the docs for your specific format to find methods/members available for your specific format.

alias File = T.FileImpl;

Alias to allow for easy referencing the proper archive File member type for Policy.

alias Directory = T.DirectoryImpl;

Alias to allow for easy referencing the proper archive Directory member type for Policy.

alias Properties = T.Properties;

(Optional) Alias to allow for easy referencing the proper archive Properties type for Policy. e.g. Tar archives do not have any archive-wide properties, while zip files have an archive comment.

this(void[] data);

Constructor for archives which initializes the archive with the contents of the serialized archive stored in data.

Params:

void[] data

serialized data of an archive in the proper format for the Policy.

this();

Constructor for read/write archives which does not require serialized data to create.

@property int delegate(int delegate(ref File)) files();

Provides access to all files in the archive via a delegate method. This allows use in foreach loops.

Example:

   foreach(file; archive.files)
   {
       // Use properties of file
   }

@property int delegate(int delegate(ref Directory)) directories();

Provides access to all directories in the archive via a delegate method. This allows use in foreach loops.

Example:

   foreach(dir; archive.directories)
   {
       // Use properties of dir
   }

@property int delegate(int delegate(ref ArchiveMember)) members();

Provides access to all files and directories in the archive via a delegate method. This allows use in foreach loops.

Example:

   foreach(member; archive.members)
   {
       if(member.isFile())
       {
           auto file = cast(archive.File)member;
           // Use properties of file
       }
       else
       {
           auto dir = cast(archive.Directory)member;
           // Use properties of dir
       }
   }

File getFile(string path);

Returns:
The file associated with the given path variable, or null if no such file exists in the archive.

Directory getDirectory(string path);

Returns:
The directory associated with the given path variable, the root for "/", or null if no such directory exists.

size_t numFiles(size_t n = size_t.max);

Returns:
the number of files in the archive which are up to n levels deep (inclusive).

size_t numDirectories(size_t n = size_t.max);

Returns:
The number of directories in the archive which are up to n levels deep (inclusive).

size_t numMembers(size_t n = size_t.max);

Returns:
The number of directories and files in the archive which are up to n levels deep (inclusive).

void[] serialize();

Serializes the archive.

Returns:
the archive in a void[] array which can be saved to a file, sent over a network connection, etc.

void addFile(File member);

Adds a file to the archive. If the path to the file contains directories that are not in the archive, they are added.

Throws:
IllegalPathException when an element in the given path is already used for a file/directory or the path is otherwise invalid.

Example:

// inserts apple.txt into the archive.
archive.addFile(new archive.File("apple.txt"));

// inserts directory animals (if not exists) and dogs.txt into the archive.
archive.addFile(new archive.File("animals/dogs.txt"));

Directory addDirectory(string path);

Adds a directory to the archive. If the path to the directory contains directories that are not in the archive, they are added. If the directory already exists it is not replaced with an empty directory.

Returns:
the final Directory in the path. (e.g. "dlang" for "languages/dlang/")

Throws:
IllegalPathException when an element in the given path is already used for a file or the path is otherwise invalid.

Example:

// inserts animals/birds/ into the archive.
archive.addDirectory("animals/");

// inserts directory languages (if not exists) and dlang into the archive.
archive.addDirectory("languages/dlang/");

bool removeFile(string path);

Removes a file from the archive.

Returns:
true if the file was removed, false if it did not exist.

bool removeDirectory(string path);

Removes a directory (and all contained files and directories) from the archive.

Returns:
true if the directory was removed, false if it did not exist.

void removeEmptyDirectories();

Removes all directories in the archive with no direct files or files in subdirectories.

Properties properties;

(Optional) Archive-wide properties for the format associated with Policy. e.g. Tar archives do not have any archive-wide properties, while zip files have an archive comment.

Directory root;

The root directory of the archive. Public here to allow for manual recursive algorithms.

class IllegalPathException: object.Exception;

Thrown when a supplied path is invalid.

class NullArchiveFilter;

Default filter which performs no mutation to the input/output data.

class ArchiveMember;

Common base class for all Archive members (Files and Directories). Provides common name management functionality and ability to iterate over both Files and Directories at once.

@property bool isDirectory();

Returns:
true if this member is a directory, false otherwise.

@property bool isFile();

Returns:
false if this member is a file, false otherwise.

@property string name();

Gets the final element in the path of this member. e.g. for the path "a/b/c/e/fg.txt" the result is "fg.txt"

Returns:
the final element in the path of this member.

@property void name(string newname);

Sets the final element in the path of this member. e.g. for the path "a/b/c/e/fg.txt" the changed path part will be "fg.txt"

Warning:
Do not use this property while this member is currently part of an archive.

@property string path();

Gets the path of this member.

Returns:
the path of this member.

@property void path(string newpath);

Sets the path of this member.

Warning:
Do not use this property while this member is currently part of an archive.

class ArchiveDirectory(Policy): ArchiveMember;

Base class for archive directories. Provides common subdirectory and file management.

alias File = Policy.FileImpl;

Alias for referencing the correct File class in the Policy.

alias Directory = Policy.DirectoryImpl;

Alias for referencing the correct Directory class in the Policy.

this();

Default constructor for ArchiveDirectories. Used to create the root archive.

Note:
Do not use without a subsequent call to *at least* .path = "path".

this(string mypath);
this(string[] parts);

Constructs a new ArchiveDirectory with the given path name.

int filesOpApply(int delegate(ref File) dg);

opApply method used for file iteration.

int directoriesOpApply(int delegate(ref Directory) dg);

opApply method used for directory iteration.

int membersOpApply(int delegate(ref ArchiveMember) dg);

opApply method for member iteration.

Directory[string] directories;

Subdirectories in this directory. Allows access to directories during manual recursion of the Directory structure.

File[string] files;

Files in this directory. Allows access to files during manual recursion of the Directory structure.