Create a docx (Word) document by using Perl (module)

Creating DOCX (Word) Documents with Perl

Learn how to programmatically generate and manipulate .docx files using Perl modules, enabling automated report generation, document customization, and more.

Generating Microsoft Word (.docx) documents programmatically can be a powerful tool for automation, report generation, and dynamic content creation. While many languages offer robust libraries for this task, Perl, with its extensive CPAN ecosystem, provides excellent modules to achieve this. This article will guide you through the process of creating and modifying DOCX files using Perl, focusing on the Docx::Writer module.

Understanding the DOCX Format

Before diving into code, it's helpful to understand that a .docx file is essentially a ZIP archive containing several XML files. These XML files define the document's structure, content, styles, and relationships between different parts. Key components include document.xml (main content), styles.xml (formatting), and _rels/.rels (relationships). Perl modules abstract away this complexity, allowing you to interact with the document at a higher level.

flowchart TD
    A[DOCX File] --> B{Unzip}
    B --> C[document.xml]
    B --> D[styles.xml]
    B --> E[media/]
    B --> F[_rels/.rels]
    C --> G["Main Content (Text, Paragraphs)"]
    D --> H["Document Styles (Fonts, Sizes)"]
    E --> I["Images, Embedded Objects"]
    F --> J["Relationships (Internal/External Links)"]

Simplified structure of a DOCX file

Getting Started with Docx::Writer

The Docx::Writer module is a popular choice for creating DOCX files in Perl. It provides a straightforward API to add text, paragraphs, headings, tables, and more. First, you'll need to install it from CPAN.

cpanm Docx::Writer

Installing the Docx::Writer module

Once installed, you can begin writing your Perl script. The basic workflow involves creating a new Docx::Writer object, adding content to it, and then saving the document to a file.

use strict;
use warnings;
use Docx::Writer;

# Create a new DOCX document
my $doc = Docx::Writer->new();

# Add a title
$doc->add_heading('My First Perl-Generated Document', 1);

# Add a paragraph of text
$doc->add_paragraph('This document was created entirely using Perl and the Docx::Writer module. It demonstrates basic text and heading insertion.');

# Add another paragraph with some formatting
$doc->add_paragraph(
    'Here is some ',
    { text => 'bold text', bold => 1 },
    ' and some ',
    { text => 'italic text', italic => 1 },
    '.'
);

# Save the document
$doc->write_file('my_first_document.docx');

print "Document 'my_first_document.docx' created successfully.\n";

Basic Perl script to create a DOCX document

Adding More Complex Elements: Tables and Lists

Beyond basic text, Docx::Writer allows you to insert more structured content like tables and lists, which are crucial for reports and organized data presentation.

use strict;
use warnings;
use Docx::Writer;

my $doc = Docx::Writer->new();

$doc->add_heading('Document with Tables and Lists', 1);

# Add a simple bulleted list
$doc->add_heading('Shopping List', 2);
$doc->add_list_item('Apples');
$doc->add_list_item('Milk');
$doc->add_list_item('Bread');

# Add a numbered list
$doc->add_heading('Steps to Success', 2);
$doc->add_list_item('Plan your project', { list_type => 'numbered' });
$doc->add_list_item('Write the code', { list_type => 'numbered' });
$doc->add_list_item('Test thoroughly', { list_type => 'numbered' });

# Add a table
$doc->add_heading('Product Sales Data', 2);
$doc->add_table(
    [ 'Product', 'Q1 Sales', 'Q2 Sales' ],
    [ 'Laptop', '1200', '1500' ],
    [ 'Mouse', '500', '650' ],
    [ 'Keyboard', '800', '900' ]
);

$doc->write_file('complex_document.docx');

print "Document 'complex_document.docx' created successfully.\n";

Perl script demonstrating tables and lists in DOCX

Advanced Features and Considerations

While Docx::Writer is excellent for creating documents from scratch, more advanced scenarios might involve templates, custom styles, or embedding images. For these, you might explore other modules like Docx::Template or combine Docx::Writer with other XML manipulation tools if direct XML modification is needed.

When working with templates, you typically create a .docx file with placeholders (e.g., {{variable_name}}) and then use a module to replace these placeholders with dynamic data. This approach separates content generation from document design.

flowchart LR
    A["Template DOCX (with placeholders)"] --> B["Perl Script (Docx::Template)"]
    B --> C["Data Source (DB, API, CSV)"]
    C --> B
    B --> D["Generated DOCX (filled data)"]

Workflow for generating DOCX from a template

For embedding images, Docx::Writer provides an add_image method. You'll need to specify the path to the image file and optionally its width and height.

use strict;
use warnings;
use Docx::Writer;

my $doc = Docx::Writer->new();

$doc->add_heading('Document with Image', 1);
$doc->add_paragraph('Below is an example image embedded in the document.');

# Assuming 'my_image.png' exists in the same directory
# You might need to provide a full path or ensure the image is accessible.
$doc->add_image('my_image.png', { width => 300, height => 200 });

$doc->write_file('document_with_image.docx');

print "Document 'document_with_image.docx' created successfully.\n";

Embedding an image into a DOCX document