p:text-join (3.1)

Concatenates text documents.

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

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:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`text`	`true`	The sequence of text documents to concatenate.
`output`	`result`	`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, 
) 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.