p:text-join (3.1) 

Concatenates text documents.

Summary

<p:declare-step type="p:text-join">
  <input port="source" primary="true" content-types="text" sequence="true"/>
  <output port="result" primary="true" content-types="text" sequence="false"/>
  <option name="override-content-type" as="xs:string?" required="false" select="'text/plain'"/>
  <option name="prefix" as="xs:string?" required="false" select="()"/>
  <option name="separator" as="xs:string?" required="false" select="()"/>
  <option name="suffix" as="xs:string?" required="false" select="()"/>
</p:declare-step>

The p:text-join step takes the document(s) appearing on its source port and concatenates these.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

text

true

The sequence of text documents to concatenate.

result

output

true

text

false

The resulting text document.

Options:

Name

Type

Req?

Default

Description

override-content-type

xs:string?

false

text/plain

The media type of the result document (the value for the result content-type document-property). This must be a text media type (text/*).

prefix

xs:string?

false

()

A prefix string for the result document (also used when there are no documents on the source port).

separator

xs:string?

false

()

A separator string to insert in between adjacent documents.

suffix

xs:string?

false

()

A suffix string for the result document (also used when there are no documents on the source port).

Description

The p:text-join step takes the document(s) appearing on its source port and concatenates these (in order of appearance).

Using the separator, prefix and suffix options it is possible to insert additional strings in between the documents, before the first document, or after the last document.

Examples

Basic usage

Assume we have three source text documents:

  • to-join-01.txt

    First document to join!
  • to-join-02.txt

    Second document to join! It's getting better…
  • to-join-03.txt

    Third document to join! Last but not least!

Straight concatenation using p:text-join looks like this:

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

  <p:input port="source" sequence="true">
    <p:document href="to-join-1.txt"/>
    <p:document href="to-join-2.txt"/>
    <p:document href="to-join-3.txt"/>
  </p:input>
  <p:output port="result"/>

  <p:text-join/>

</p:declare-step>

Result document:

First document to join!
Second document to join! It's getting better…
Third document to join! Last but not least!

And this is what happens if we use the separator, prefix and suffix options:

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

  <p:input port="source" sequence="true">
    <p:document href="to-join-1.txt"/>
    <p:document href="to-join-2.txt"/>
    <p:document href="to-join-3.txt"/>
  </p:input>
  <p:output port="result"/>

  <p:text-join separator="=========&#xA;" prefix="==START==&#xA;" suffix="==END==&#xA;"/>

</p:declare-step>

Result document:

==START==
First document to join!
=========
Second document to join! It's getting better…
=========
Third document to join! Last but not least!
==END==

Notice the use of the line-end character (line-feed, &#xA;) in the option values. This will cause the inserted strings to become separate lines.

When there are no documents on the source port, the prefix and suffix options still apply:

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

  <p:input port="source" sequence="true">
    <p:empty/>
  </p:input>
  <p:output port="result"/>

  <p:text-join separator="=========&#xA;" prefix="==START==&#xA;" suffix="==END==&#xA;"/>

</p:declare-step>

Result document:

==START==
==END==

Additional details

  • No document-properties from the source document(s) survive. The joined document has no base-uri document-property.

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

Errors raised

Error code

Description

XC0001

It is a dynamic error if the value of option override-content-type is not a text media type.

XD0079

It is a dynamic error if a supplied content-type is not a valid media type of the form “type/subtype+ext” or “type/subtype”.

Reference information

This description of the p:text-join 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-join step can be found here.

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

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