p:text-head (3.1) 

Returns lines from the beginning of a text document.

Summary

<p:declare-step type="p:text-head">
  <input port="source" primary="true" content-types="text" sequence="false"/>
  <output port="result" primary="true" content-types="text" sequence="false"/>
  <option name="count" as="xs:integer" required="true"/>
</p:declare-step>

The p:text-head step returns lines from the beginning of a text document.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

text

false

The text document to get the lines from.

result

output

true

text

false

The resulting lines.

Options:

Name

Type

Req?

Description

count

xs:integer

true

Indicates what p:text-head should do:

  • If positive, p:text-head returns the first count lines.

  • If zero, p:text-head returns all lines.

  • If negative, p:text-head returns all lines except the first count lines.

Description

The p:text-head step takes lines from the beginning of the text document appearing on its source port and returns these lines as a text document on its result port. What exactly happens depends on the value of the count option.

As you might have guessed there is also a step that returns lines from the end of a document: p:text-tail.

Examples

Basic usage

Assume we have a text document, called lines.txt, that looks like this and we want to get the first 2 lines using p:text-head:

line 1
line 2
line 3
line 4
line 5

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-head count="2"/>

</p:declare-step>

Result document:

line 1
line 2

Setting the count option to 0 will simply return the original document (the step now acts like a p:identity step).

Setting the count option to -2 will return all lines except the first two:

<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-head count="-2"/>

</p:declare-step>

Result document:

line 3
line 4
line 5

Additional details

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

  • What exactly constitutes a line-end is defined in the XML specification.

  • All lines returned by p:text-head are terminated with a line-end character (line-feed, &#xA;).

Reference information

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

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

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