p:text-replace (3.1)

Replace substrings in a text document.

Summary
Description
Examples
- Basic usage
Additional details
Errors raised
Reference information

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:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`text`	`false`	The text document to replace the substrings in.
`output`	`result`	`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 fn:replace() for more details.
`replacement`	`xs:string`	`true`		The replacement string. See the `$replacement` argument of the XPath function fn: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.

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 fn:replace() for more details.

replacement

xs:string

true

The replacement string.

See the $replacement argument of the XPath function fn: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 fn: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.