section.1.in

.TH section 1 "@DATE@" @VERSION@ "print indented sections"

.SH NAME
section \- print indented text sections selected via matching a pattern

.SH SYNOPSIS
.B section
.I [OPTIONS] PATTERN [FILE...]

.SH DESCRIPTION
The
.B section
filter searches for
.I PATTERN
in each
.I FILE
(or standard input if no
.I FILE
is given), and prints the sections selected by matching lines
together with the chosen section algorithm variant
to standard output.
.P
A section comprises all deeper indented lines directly following the
starting line of the section.
The starting line of a section can also be called the section
.IR header .
.P
By default, sections are started by lines matching the
.IR PATTERN .
.P
By default,
.I PATTERN
is a regular expression, see section
.B "REGULAR EXPRESSIONS"
below.

.SH OPTIONS
Options can be used to modify the operation of
.BR section .
.B section
uses Go's
.I flag
package for option processing.
.P
Using the two character sequence
.B \-\-
(two hyphens) in an option position ends option processing.
This allows the
.I PATTERN
to start with a hyphen.

.SS Print information about the section binary:
.TP
.SS \-h, \-\-help
Write a help message to standard output.
.TP
.SS \-V, \-\-version
Write version information to standard output.

.SS Use a non-default section algorithm variant:
The
.B section
filter can use one of several ways to determine the start of a selected section.
By default,
sections start with a line that matches the
.IR PATTERN .
.TP
.SS \-\-enclosing
Sections enclose the line matching the
.IR PATTERN .
Each section starts at the last line preceding the line matching the
.I PATTERN
with less indentation.
If no such line exists, the section starts with the line matching the
.IR PATTERN .
This option has no effect when combined with the
.B \-\-top\-level
option.
.TP
.SS \-\-top\-level
Sections always start from the
.I top
.IR level ,
i.e., the minimum indentation level, instead of from the line matching the
.IR PATTERN .
A line matching the
.I PATTERN
selects the complete top level section.

.SS Control pattern matching:
.TP
.SS \-F, \-\-fixed\-string
Indicate that the
.I PATTERN
shall be interpreted as a fixed string, not as a regular expression.
.TP
.SS \-i, \-\-ignore\-case
Ignore case distinctions for pattern matching,
so that characters that differ only in case match each other.
.TP
.SS \-\-invert\-match
Match sections
.B not
selected with the
.IR PATTERN .

.SS Control section boundary determination:
Section boundary determination is based on matching the
.I PATTERN
and the indentation level of lines.
.P
Specific lines can be ignored for section boundary determination.
Ignored lines are not checked for matching the
.IR PATTERN .
Therefore they do not select a section.
The indentation level of ignored lines is not considered either,
therefore sections always continue across them.
.TP
.SS \-\-ignore\-blank
Ignore blank lines when determining section boundaries.
.TP
.SS \-\-ignore\-re IGNORE_RE
Ignore lines matching
.I IGNORE_RE
when determining section boundaries.
The
.B \-\-ignore\-blank
option overrides the
.B \-\-ignore\-re
option.
.P
By default, leading space and tab characters constitute the indentation
of a line.
Indentation depth determines which lines form a section.
.TP
.SS \-\-indent\-re INDENT_RE
Use non-default regular expression
.I INDENT_RE
to describe indentation.
The
.B \-\-yaml\-seq\-indent
option overrides this.
.TP
.SS \-\-tab\-size SIZE
Tab characters inside the indentation increase the indentation depth to
the value of the next tab stop.
Each tab stop is at a character position that is an integer multiple of
.IR SIZE,
starting with character position
.IR SIZE.
The default value of
.I SIZE
is 8.
.IP
Setting
.I SIZE
to 1 results in treating tab characters identically to space characters.
.TP
.SS \-\-yaml\-seq\-indent
Accept trailing YAML sequence (list) indentation in addition to white space
based indentation.
This results in considering a YAML sequence used as a value in a YAML mapping
as further indented than the key,
even if the
.I dash
has the same indentation depth as the key.

.SS Select additional lines:
.TP
.SS \-\-begin
Select all lines following the first line selected by the chosen section
algorithm variant.
If multiple
.IR FILE s
are given,
each
.I FILE
is considered independently.
.TP
.SS \-\-headers
In addition to the sections selected according to the chosen algorithm,
also select starting lines (headers) of enclosing sections,
up to the top level.
This option has no effect when combined with the
.B \-\-top\-level
option.

.SS Control output contents:
.TP
.SS \-\-omit
Omit (exclude) matched sections,
print everything else instead.
.TP
.SS \-\-omit\-ignored
Do not print lines that are ignored when determining section boundaries.
.TP
.SS \-q, \-\-quiet, \-\-silent
Suppress all normal output.
The exit code can be used to determine if the
.I PATTERN
was matched or not, or if an error occurred.
Error messages are still printed.

.SS Control output format:
.TP
.SS \-\-label LABEL
Use
.I LABEL
instead of the default of
.B (standard input)
in place of a file name for data from standard input when the
.B \-\-with\-filename
option is given.
.TP
.SS \-n, \-\-line\-number
Prefix each output line with the line number in the respective input file,
followed by the prefix delimiter.
The line number is added after the file name when both options
.B \-\-line\-number
and
.B \-\-with\-filename
are given.
.TP
.SS \-\-prefix\-delimiter DELIMITER
Use the given
.I DELIMITER
instead of the default of a colon
.RB ( : )
as prefix delimiter.
.I DELIMITER
need not be a single character.
.TP
.SS \-\-separator
Print a separator line between matched sections.
This allows distinguishing separate sections in the output independent of the
indentation of individual lines.
The output produced when using this option is a simple form of stanza format
without line continuations.
.IP
When used together with
.BR \-\-omit ,
consecutively omitted sections are indicated by a single separator line.
.TP
.SS \-\-separator\-string SEPARATOR
Use the given
.I SEPARATOR
instead of the default of two ASCII hyphen characters
.RB ( \-\- )
when printing section separators.
A newline is printed after the separator string.
.TP
.SS \-\-with\-filename
Prefix each output line with the file name, followed by the prefix delimiter.
The file name is added in front of the line number when both options
.B \-\-with\-filename
and
.B \-\-line\-number
are given.

.SH "REGULAR EXPRESSIONS"
.B section
uses Go's
.I regexp
package, and thus understands the
.I RE2
syntax.

.SH EXIT STATUS
.IP \(bu
0, if at least one line matched the
.I PATTERN
.IP \(bu
1, if no line matched the
.I PATTERN
.IP \(bu
2, if an error occurred

.SH "BUGS AND LIMITATIONS"
.IP \(bu
The maxmimum line size supported by
.B section
is
.IR "512 MiB" .
.IP \(bu
Regular expressions are limited to those supported by Go's
.I regexp
package.
.IP \(bu
Options are implemented with Go's
.I flag
package.
Thus single character options cannot be combined,
options longer than a single character cannot be abbreviated,
and all options can be started by either a single or a double hyphen.
Additionally, all options must come before the first non-option
argument (i.e., the
.IR PATTERN ).
.IP \(bu
YAML sequences are not handled well, because
.B section
does not parse the YAML format.
Giving the
.B \-\-yaml\-seq\-indent
option does not change this.
The structure created by YAML sequence indicators is ignored by
.BR section .
.B section
always uses indentation depth to determine sections.

.SH AUTHOR
.B section
was written by Erik Auerswald <auerswal@unix\-ag.uni\-kl.de>.

.SH COPYRIGHT
Copyright \(co @CRYEARS@ Erik Auerswald.
License GPLv3+: GNU GPL version 3 or later
.UR https://gnu.org/licenses/gpl.html
.UE
.P
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

.SH "SEE ALSO"
.BR awk (1),
.BR grep (1),
.BR expand (1),
.BR unexpand (1),
.P
.B go doc
.IR flag ,
.B go doc
.IR regexp ,
.P
.UR https://github.com/google/re2/wiki/Syntax
.UE ,
.P
.UR https://www.unix\-ag.uni\-kl.de/~auerswal/section/
.UE