p:text-replace (3.1) 

Replace substrings in a text document.

Summary

<p:declare-step type="p:text-replace">
  <input port="source" primary="true" content-types="text" sequence="false"/>
  <output port="result" primary="true" content-types="text" sequence="false"/>
  <option name="pattern" as="xs:string" required="true"/>
  <option name="replacement" as="xs:string" required="true"/>
  <option name="flags" as="xs:string?" required="false" select="()"/>
</p:declare-step>

The p:text-replace step takes the text document appearing on its source port and replaces substrings that match a regular expression with a replacement string.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

text

false

The text document to replace the substrings in.

result

output

true

text

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

pattern

xs:string

true

 

The XPath regular expression that matches the substrings to replace.

See the $pattern argument of the XPath function replace() for more details.

replacement

xs:string

true

 

The replacement string.

See the $replacement argument of the XPath function replace() for more details.

flags

xs:string?

false

()

Flags governing the matching process.

See the description of regular expression flags in the XPath standard for more details.

Description

The p:text-replace step is “just” a convenience wrapper around the Xpath replace() function. This function takes a string and replaces substrings that match a regular expression with a replacement string. For the p:text-replace step, the input string is the full document on the source port. The resulting document appears on the result port.

Examples

Basic usage

Assume we have a text document, called lines.txt, that looks like this and we want to replace all t characters followed by an h or an e with two * characters (case-insensitive):

This is an example of a very simple text file… But simple is often the best!

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" href="lines.txt"/>
  <p:output port="result"/>

  <p:text-replace pattern="t[h|e]" replacement="**" flags="i"/>

</p:declare-step>

Result document:

**is is an example of a very simple **xt file… But simple is of**n **e best!

Additional details

  • p:text-replace preserves all document-properties of the document(s) appearing on its source port.

  • This operation does not require identifying lines. Therefore, no special end-of-line handling is performed.

Errors raised

Error code

Description

XC0147

It is a dynamic error if the specified value is not a valid XPath regular expression.

Reference information

This description of the p:text-replace step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:text-replace step can be found here.

The p:text-replace step is part of categories:

The p:text-replace step is also present in version: 3.0.