NAME

MsOffice::Word::Surgeon - tamper wit the guts of Microsoft docx documents

SYNOPSIS

  my $surgeon = MsOffice::Word::Surgeon->new(docx => $filename);

  # extract plain text
  my $text = $surgeon->plain_text;

  # simplify the internal XML structure -- so that later replacements work better
  $surgeon->reduce_all_noises;
  $surgeon->unlink_fields;
  $surgeon->merge_runs;

  # anonymize
  my %alias = ('Claudio MONTEVERDI' => 'A_____', 'Heinrich SCHÜTZ' => 'B_____');
  my $pattern = join "|", keys %alias;
  my $replacement_callback = sub {
    my %args =  @_;
    return $surgeon->change(to_delete => $args{matched},
                            to_insert => $alias{$args{matched}},
                            author    => __PACKAGE__,
                           );
  };
  $surgeon->replace(qr[$pattern], $replacement_callback);

  # save the result
  $surgeon->overwrite; # or ->save_as($new_filename);

DESCRIPTION

Purpose

This module supports a few operations for modifying or extracting text from Microsoft Word documents in '.docx' format -- therefore the name 'surgeon'. Since a surgeon does not give life, there is no support for creating fresh documents; if you have such needs, use one of the other packages listed in the "SEE ALSO" section.

Some applications for this module are :

content extraction in plain text format;
unlinking fields (equivalent of performing Ctrl-Shift-F9 on the whole document)
regex replacements within text, for example for :
- anonymization, i.e. replacement of names or adresses by aliases;
- templating, i.e. replacement of special markup by contents coming from a data tree
pretty-printing the internal XML structure

Operating mode

The format of Microsoft .docx documents is described in http://www.ecma-international.org/publications/standards/Ecma-376.htm and http://officeopenxml.com/. An excellent introduction can be found at https://www.toptal.com/xml/an-informal-introduction-to-docx. Internally, a document is a zipped archive, where the member named word/document.xml stores the main document contents, in XML format.

The present module does not parse all details of the whole XML structure because it only focuses on text nodes (those that contain literal text) and run nodes (those that contain text formatting properties). All remaining XML information, for example for representing sections, paragraphs, tables, etc., is stored as opaque XML fragments; these fragments are re-inserted at proper places when reassembling the whole document after having modified some text nodes.

Status

This is the first release; the software architecture is quite stable but the module is not battle-proofed. Minor changes to the public interface may occur in future versions.

METHODS

Constructor

new

  my $surgeon = MsOffice::Word::Surgeon->new(docx => $filename);
  # or simply : ->new($filename);

Builds a new surgeon instance, initialized with the contents of the given filename.

Contents restitution

Returns a Perl string with the current internal XML representation of the document contents.

original_contents

Returns a Perl string with the XML representation of the document contents, as it was in the ZIP archive before any modification.

indented_contents

Returns an indented version of the XML contents, suitable for inspection in a text editor. This is produced by "toString" in XML::LibXML::Document and therefore is returned as an encoded byte string, not a Perl string.

plain_text

Returns the text contents of the document, without any markup. Paragraphs are converted to newlines, all other formatting instructions are ignored.

runs

Returns a list of MsOffice::Word::Surgeon::Run objects. Each of these objects holds an XML fragment; joining all fragments restores the complete document.

  my $contents = join "", map {$_->as_xml} $self->runs;

Modifying contents

reduce_noise

  $surgeon->reduce_noise($regex1, $regex2, ...);

This method is used for removing unnecessary information in the XML markup. It applies the given list of regexes to the whole document, suppressing matches. The final result is put back into $self->contents. Regexes may be given either as qr/.../ references, or as names of builtin regexes (described below). Regexes are applied to the whole XML contents, not only to run nodes.

noise_reduction_regex

  my $regex = $surgeon->noise_reduction_regex($regex_name);

Returns the builtin regex corresponding to the given name. Known regexes are :

  proof_checking       => qr(<w:(?:proofErr[^>]+|noProof/)>),
  revision_ids         => qr(\sw:rsid\w+="[^"]+"),
  complex_script_bold  => qr(<w:bCs/>),
  page_breaks          => qr(<w:lastRenderedPageBreak/>),
  language             => qr(<w:lang w:val="[^/>]+/>),
  empty_run_props      => qr(<w:rPr></w:rPr>),

reduce_all_noises

  $surgeon->reduce_all_noises;

Applies all regexes from the previous method.

unlink_fields

Removes all fields from the document, just leaving the current value stored in each field. This is the equivalent of performing Ctrl-Shift-F9 on the whole document.

merge_runs

  $surgeon->merge_runs(no_caps => 1); # optional arg

Walks through all runs of text within the document, trying to merge adjacent runs when possible (i.e. when both runs have the same properties, and there is no other XML node inbetween).

This operation is a prerequisite before performing replace operations, because documents edited in MsWord often have run boundaries across sentences or even in the middle of words; so regex searches can only be successful if those artificial boundaries have been removed.

If the argument no_caps => 1 is present, the merge operation will also convert runs with the w:caps property, putting all letters into uppercase and removing the property; this makes more merges possible.

replace

  my $xml = $surgeon->replace($pattern, $replacement, %replacement_args);

Replaces all occurrences of $pattern regex within the text nodes by the given $replacement, and returns new XML corresponding to the whole document contents after all these operations. This is not exactly like a search-replace operation performed within MsWord, because the search does not cross boundaries of text nodes; so it is highly recommended to call "merge_runs" before invoking replace(), to maximize the chances of successful replacements.

The argument $pattern can be either a string or a reference to a regular expression. It should not contain any capturing parentheses, because that would perturb text splitting operations.

The argument $replacement can be either a fixed string, or a reference to a callback subroutine that will be called for each match. The subroutine will receive a copy of %replacement_args, enriched with three entries :

matched: The string that has been matched by $pattern.
run: The run object in which this text resides.
xml_before: The XML fragment (possibly empty) found before the matched text .

The callback subroutine may return either plain text or structured XML. See the "SYNOPSIS" for an example of a replacement callback.

change

  my $xml = $surgeon->change(
    to_delete   => $text_to_delete,
    to_insert   => $text_to_insert,
    author      => $author_string,
    date        => $date_string,
    run         => $run_object,
    xml_before  => $xml_string,
  );

This method generates markup for MsWord tracked changes. Users can then manually review those changes within MsWord and accept or reject them. This is best used in collaboration with the "replace" method : the replacement callback can call $self->change(...) to generate tracked change marks in the document.

All parameters are optional, but either to_delete or to_insert (or both) must be present. The parameters are :

to_delete: The string of text to delete (usually this will be the matched argument passed to the replacement callback).
to_insert: The string of new text to insert.
author: A short string that will be displayed by MsWord as the "author" of this tracked change.
date: A date (and optional time) in ISO format that will be displayed by MsWord as the date of this tracked change. The current date and time will be used by default.
run: A reference to the MsOffice::Word::Surgeon::Run object surrounding this tracked change. The formatting properties of that run will be copied into the <w:r> nodes of the deleted and inserted text fragments.
xml_before: An optional XML fragment to be inserted before the <w:t> node of the inserted text

This method delegates to the MsOffice::Word::Surgeon::Change class for generating the XML markup.

AUTHOR

Laurent Dami, <dami AT cpan DOT org<gt>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install MsOffice::Word::Surgeon, copy and paste the appropriate command in to your terminal.

cpanm

cpanm MsOffice::Word::Surgeon

CPAN shell

perl -MCPAN -e shell
install MsOffice::Word::Surgeon

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)