Reference

Command line

Read a pipe-hat message without counting pipes. Install with cargo install er7.

Synopsis

er7 [OPTIONS] [FILE]

FILE holds one or more messages, or a batch file. - or no argument reads standard input. Input is split into messages, and every message is parsed before anything is written, so a malformed message late in a batch fails the run rather than producing half an output.

Option	Effect
`-q, --query <PATH>`	Print the values at an HL7 path, one per line. May be repeated; outputs appear in the order the options were given.
`-n, --normalize`	Rewrite the input as canonical ER7, with a trailing terminator on every message.
`-m, --message <N>`	Use only the Nth message of the input, counting from 1.
`-r, --raw`	Show text as sent, without decoding escape sequences.
`-t, --terminator <KIND>`	Segment terminator to write: cr (default), lf, crlf.
`-o, --output <FILE>`	Write to FILE instead of standard output.
`-h, --help`	Print usage.
`-V, --version`	Print the version.

Combining --query with --normalize is an error: they ask for different output, and silently preferring one would hide a mistake in a script.

The default action The outline

The reason the command exists: it answers “which position is this value actually in?”, which is the hardest thing about a positional format.

MSH-1       |
MSH-2       ^~\&
MSH-9.1     ORU
PID-3.4.2   1.2.840.114398.1.100
PID-5.1     EVERYWOMAN
PID-13[1]   555-555-1111
PID-13[2]   555-555-2222
OBX[1]-3.2  Cholesterol
OBX[2]-3.2  Triglycerides

Every label is a valid --query argument. This is the point of the format: a path read off the outline can be pasted straight back in.
A level with only one child is not indexed, so a name sent as a single component reads NTE-3, not NTE-3.1. Indices appear exactly where they disambiguate.
Repeated segments are labelled OBX[2]-…; repeated fields are labelled PID-13[2].
Positions with no value are left out entirely.
An explicit null is shown as the "" it was sent as, since that is exactly what distinguishes it from a field left out.
Carriage returns, line feeds, and tabs inside a decoded value are shown as \r, \n, and \t, so one value stays on one line.

When the input holds more than one message, each outline is preceded by a # message N heading naming the message code, trigger event, control ID, and version where the message supplies them.

Recipes

Inspect an unfamiliar message

er7 suspect.er7 | less
er7 suspect.er7 | grep '^PID'
er7 --raw suspect.er7 | grep '\\'    # find every escape sequence

Extract values for a script

# One value
er7 --query PID-5.1 message.er7

# Several paths, in the order given
er7 -q PID-5.1 -q PID-7 -q OBX-5 message.er7

# Exactly as sent, escapes intact
er7 --raw --query OBX-5 message.er7

Make a message readable

# ER7 ends segments with a carriage return, so a terminal draws them
# on top of each other. Rewrite with line feeds instead.
er7 --normalize --terminator lf message.er7

Work through a batch file

# Outline every message, with headings
er7 batch.er7

# Just the second one
er7 --message 2 batch.er7

# The control ID of every message
er7 --query MSH-10 batch.er7

From a pipe

cat message.er7 | er7
er7 - < message.er7
er7 message.er7 --output outline.txt

Exit codes and diagnostics

Code	Meaning
`0`	success
`1`	any error: bad arguments, unreadable input, a message that failed to parse, or an unwritable output

Diagnostics go to standard error, prefixed er7: error:, one line. A message that failed to parse is identified by its 1-based position in the input.

er7: error: message 3: input contains no HL7 segments

A query that matches nothing prints nothing and still exits 0. The message simply did not carry that value, which is not a failure. Scripts that need to distinguish should test for empty output.

A closed output pipe (er7 … | head -3) also exits 0, which is what every other Unix filter does.

Stability

The command line is covered by the same semantic-versioning promise as the library: removing an option, changing an exit code, or changing the outline’s label format is a breaking change. Adding an option is not.