p:text-head (3.1)

Returns lines from the beginning of a text document.

Summary
Description
Examples
- Basic usage
Additional details
Reference information

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:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`text`	`false`	The text document to get the lines from.
`output`	`result`	`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.

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, 
).

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.