section

NAME

section - print indented text sections selected via matching a pattern

SYNOPSIS

section [OPTIONS] PATTERN [FILE...]

DESCRIPTION

The section filter searches for PATTERN in each FILE (or standard input if no FILE is given), and prints the sections selected by matching lines together with the chosen section algorithm variant to standard output.

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 header.

By default, sections are started by lines matching the PATTERN.

By default, PATTERN is a regular expression, see section REGULAR EXPRESSIONS below.

OPTIONS

Options can be used to modify the operation of section. section uses Go’s flag package for option processing.

Using the two character sequence -- (two hyphens) in an option position ends option processing. This allows the PATTERN to start with a hyphen.

Print information about the section binary:

-h, --help
Write a help message to standard output.

-V, --version
Write version information to standard output.

Use a non-default section algorithm variant:
The 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 PATTERN.

--enclosing
Sections enclose the line matching the PATTERN. Each section starts at the last line preceding the line matching the PATTERN with less indentation. If no such line exists, the section starts with the line matching the PATTERN. This option has no effect when combined with the --top-level option.

--top-level
Sections always start from the top level, i.e., the minimum indentation level, instead of from the line matching the PATTERN. A line matching the PATTERN selects the complete top level section.

Control pattern matching:

-F, --fixed-string
Indicate that the PATTERN shall be interpreted as a fixed string, not as a regular expression.

-i, --ignore-case
Ignore case distinctions for pattern matching, so that characters that differ only in case match each other.

--invert-match
Match sections not starting with PATTERN.

Control section boundary determination:

--ignore-blank
Ignore the indentation level of blank lines, so that sections always continue across them.

--ignore-re IGNORE_RE
Ignore the indentation level of lines matching IGNORE_RE, so that sections always continue across them. The --ignore-blank option overrides this.

--indent-re INDENT_RE
Use non-default regular expression INDENT_RE to describe indentation. The --yaml-seq-indent option overrides this.

--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 SIZE, starting with character position SIZE. The default value of SIZE is 8.

Setting SIZE to 1 results in treating tab characters identically to space characters.

--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 dash has the same indentation depth as the key.

Select additional lines:

--begin
Select all lines following the first line selected by the chosen section algorithm variant. If multiple FILEs are given, each FILE is considered independently.

--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 --top-level option.

Control output contents:

--omit
Omit (exclude) matched sections, print everything else instead.

--omit-ignored
Do not print lines that are ignored when determining section breaks.

-q, --quiet, --silent
Suppress all normal output. The exit code can be used to determine if the PATTERN was matched or not, or if an error occurred. Error messages are still printed.

Control output format:

--label LABEL
Use LABEL instead of the default of (standard input) in place of a file name for data from standard input when the --with-filename option is given.

-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 --line-number and --with-filename are given.

--prefix-delimiter DELIMITER
Use the given DELIMITER instead of the default of a colon (:) as prefix delimiter. DELIMITER need not be a single character.

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

When used together with --omit, consecutively omitted sections are indicated by a single separator line.

--separator-string SEPARATOR
Use the given SEPARATOR instead of the default of two ASCII hyphen characters (--) when printing section separators. A newline is printed after the separator string.

--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 --with-filename and --line-number are given.

REGULAR EXPRESSIONS

section uses Go’s regexp package, and thus understands the RE2 syntax.

EXIT STATUS

BUGS AND LIMITATIONS

AUTHOR

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

COPYRIGHT

Copyright © 2019-2024 Erik Auerswald. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

SEE ALSO

awk(1), grep(1), expand(1), unexpand(1),

go doc flag, go doc regexp,
https://github.com/google/re2/wiki/Syntax,
https://www.unix-ag.uni-kl.de/~auerswal/section/