ar-cpp Documentation

Table of Contents

• General Information
  • Naming Conventions
  • Includes
  • Namespaces
  • Error Handling
• Library Usage
  • Extraction of Archives
  • Working With Files
  • A Complete Example
• Contact

This is an automatically generated API documentation for the ar-cpp library.

General Information

We start by giving you some general information concerning the library. Then, we describe how you can use library.

Naming Conventions

The library uses the following naming conventions:

• Include files are named by using snake_case, e.g. extract.h.
• Functions and variables are named by using camelCase, e.g. extract().
• Classes and constants are named by using CamelCase, e.g. File.

Includes

The easiest way to use the library is to include the general header file ar.h that includes all the necessary header files:

#include <ar/ar.h>

However, if you use only specific parts of the library, you can include just the used header files:

#include <ar/extraction.h>
#include <ar/file.h>
// ...

Namespaces

All the classes, functions, and constants the library provides are in the ar namespace.

For simplicity, in this API documentation, this namespace is omitted, e.g. it uses just File instead of ar::File.

Error Handling

The library uses exceptions to signal errors. The base class of all custom exceptions thrown by the library is Error. Currently, the following Error subclasses may be thrown:

• InvalidArchiveError – When the input archive is invalid (e.g. corrupted headers).
• IOError – When there is an I/O error (e.g. an archive cannot be read).

Library Usage

The present section describes how to use the library to work with archives.

Extraction of Archives

To extract an archive, call extract() and pass it your archive:

auto files = extract(File::fromFilesystem("/path/to/archive.a"))

Also, if you need, you can create an archive from a given content and file name, both given as a std::string:

auto files = extract(File::fromContentWithName(content, name))

The above call creates a virtual file in memory that does not correspond to any real file on your filesystem.

Working With Files

The extract() function returns a vector-like container of the extracted files. Each file is a subclass of File. You can iterate over the files, obtain info about them, and store them to the filesystem. For example, the following snippet prints the name of each file to the standard output and saves the extracted files to the current working directory:

for (auto& file : files) {
    std::cout << file->getName() << "\n";
    file->saveCopyTo(".");
}

See the File class for a complete list of member functions it provides.

A Complete Example

The following example extracts the given archive to the current working directory and prints the name of each extracted file.

#include <iostream>
#include <ar/ar.h>

using namespace ar;

int main(int argc, char **argv) {
    if (argc != 2) {
        std::cerr << "usage: " << argv[0] << " ARCHIVE\n";
        return 1;
    }

    try {
        auto files = extract(File::fromFilesystem(argv[0]));
        for (auto& file : files) {
            std::cout << file->getName() << "\n";
            file->saveCopyTo(".");
        }
        return 0;
    } catch (const Error& ex) {
        std::cerr << "error: " << ex.what() << "\n";
        return 1;
    }
}

Contact

If you have any remarks or questions concerning the library, feel free to contact me.