Ootempl.Archive (ootempl v0.3.0)

Provides functions for working with .docx files as ZIP archives.

.docx files are ZIP archives containing XML documents and media files. This module handles extracting .docx archives to access internal content, extracting specific files, and re-packaging content into valid .docx archives.

Summary

Types

file_entry()
file_map()

Functions

cleanup(temp_path)

Removes a temporary extraction directory.

create(file_map, output_path)

Creates a .docx archive from a map of file paths to content.

extract(docx_path)

Extracts a .docx file to a temporary directory.

Types

file_entry()

@type file_entry() :: {charlist(), binary()}

file_map()

@type file_map() :: %{required(String.t()) => binary()}

Functions

cleanup(temp_path)

@spec cleanup(Path.t()) :: :ok | {:error, term()}

Removes a temporary extraction directory.

Returns :ok on success, or {:error, reason} if cleanup fails.

Examples

iex> {:ok, temp_path} = Ootempl.Archive.extract("template.docx")
iex> Ootempl.Archive.cleanup(temp_path)
:ok
iex> File.exists?(temp_path)
false

create(file_map, output_path)

@spec create(file_map(), Path.t()) :: :ok | {:error, term()}

Creates a .docx archive from a map of file paths to content.

The file_map is a map where keys are internal paths (e.g., "word/document.xml") and values are binary content.

Returns :ok on success, or {:error, reason} if creation fails.

Examples

iex> file_map = %{
...>   "word/document.xml" => "<?xml version=\"1.0\"?>...",
...>   "[Content_Types].xml" => "<?xml version=\"1.0\"?>..."
...> }
iex> Ootempl.Archive.create(file_map, "output.docx")
:ok

extract(docx_path)

@spec extract(Path.t()) :: {:ok, Path.t()} | {:error, term()}

Extracts a .docx file to a temporary directory.

Returns {:ok, temp_path} where temp_path is the directory containing the extracted contents, or {:error, reason} if extraction fails.

The caller is responsible for cleaning up the temporary directory using cleanup/1 when done, even if subsequent operations fail.

Examples

iex> {:ok, temp_path} = Ootempl.Archive.extract("template.docx")
iex> File.exists?(Path.join(temp_path, "word/document.xml"))
true
iex> Ootempl.Archive.cleanup(temp_path)
:ok