---
name: "MsOffice::Word::Surgeon::Run"
section: "3pm"
platform: "linux"
package: "libmsoffice-word-surgeon-perl"
version: "2.10-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/MsOffice::Word::Surgeon::Run"
---

# MsOffice::Word::Surgeon::Run(3pm)

internal representation for a "run of text"

## NAME

MsOffice::Word::Surgeon::Run - internal representation for a "run of text"

## DESCRIPTION

This is used internally by MsOffice::Word::Surgeon for storing a "run of text" in a MsWord document. It loosely corresponds to a `"<w:r>"` node in OOXML, but may also contain an anonymous XML fragment which is the part of the document just before the `"<w:r>"`  node -- used for reconstructing the complete document after having changed the contents of some runs.

## METHODS

### new

```
  my $run = MsOffice::Word::Surgeon::Run(
    xml_before  => $xml_string,
    props       => $properties_string,
    inner_texts => [MsOffice::Word::Surgeon::Text(...), ...],
  );
```

Constructor for a new run object. Arguments are :

- xml\_before

  A string containing arbitrary XML preceding that run in the complete document. The string may be empty but must be present.

- props

  A string containing XML for the properties of this run (for example instructions for bold, italic, font, etc.). The module does not parse this information; it just compares the string for equality with the next run.

- inner\_texts

  An array of MsOffice::Word::Surgeon::Text objects, corresponding to the XML `"<w:t>"` nodes inside the run.

### as\_xml

```
  my $xml = $run->as_xml;
```

Returns the XML representation of that run.

### merge

```
  $run->merge($next_run);
```

Merge the contents of `$next_run` together with the current run. This is only possible if both runs have the same properties (same string returned by the `"props"` method), and if the next run has an empty `"xml_before"` attribute; if the conditions are not met, an exception is raised.

### replace

```
  my $xml = $run->replace($pattern, $replacement_callback, %replacement_args);
```

Replaces all occurrences of `$pattern` within all text nodes by a new string computed by `$replacement_callback`, and returns a new xml string corresponding to the result of all these replacements. This is the internal implementation for public method "replace" in MsOffice::Word::Surgeon::PackagePart.

### remove\_caps\_property

Searches in the run properties for a `"<w:caps/>"` property; if found, removes it, and replaces all inner texts by their uppercase equivalents.

## AUTHOR

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

## COPYRIGHT AND LICENSE

Copyright 2019-2024 by Laurent Dami.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.