The Section Filter

The section filter can be used to extract indented sections of text starting with a line that matches a regular expression. The matching line(s) and any indented section(s) under the matching line(s) are printed to the standard output. Input is either read from files given as command line arguments, or from standard input.

Documentation

The section filter is documented in the manual page section.1 included in the source code archive. You can read an HTML version of the section manual page online.

The section filter prints brief usage information when invoked with either the -h or --help option.

Download

The section filter is GPL (version 3 or later) licensed free software written in Go. The source code is available for download as a Gzip compressed Tar archive. I have successfully tested compiling section, and using the resulting binary, with both the golang.org and GCC Go compilers.

Source Code

section-0.1.0.tar.gz

Development Repository

A mirror of the development repository for section is available on GitHub.

Use Cases

The section filter can be helpful when looking at textual information where indentation is used to denote hierarchy.

Some textual file formats prescribe the use of indentation, e.g., Makefiles, Python code, YAML data.

Source code is often formatted in a way that uses indentation to emphasize hierarchical relationships. This is sometimes automated, e.g., with go fmt.

The output of command line tools often uses indentation to indicate that some part of the output relates to a previous line with less indentation, e.g., the output of ip address list, or when Free Range Routing (FRR) displays its configuration.

Some text documents, e.g., the current text rendering of Internet RFCs, indent a section's textual contents deeper than the section's title.

Examples

Known Bugs and Limitations

As is the case with most software, section has bugs and limitations.

Indentation Mixing Space and Tabulation Characters

The Go implementation of the section filter does not attempt to handle indentation with mixed space and tab characters. You can use the widely available expand and unexpand filters to ensure uniform indentation for use with section.

Line Length

The Go implementation of the section filter uses Go's bufio.Scanner to split input data into lines. This imposes an arbitrary limit for the line length. Instead of the default value of 64KiB, a value of 512MiB is used.

Regular Expressions

The Go implementation of the section filter uses Go's regexp package, and thus inherits its strengths, weaknesses, and peculiarities.

Options

The Go implementation of the section filter uses Go's flag package, and thus inherits its strengths, weaknesses, and peculiarities. For example, single character options cannot be combined, options longer than a single character cannot be abbreviated, and all options can be started with either a single (-) or double (--) hyphen.

Alternative Implementations

Before starting this section implementation in the Go programming language, I wrote three simpler implementations (without any options) in the programming languages AWK (with a shell wrapper), Perl (version 5), and Python (compatible with both versions 2 and 3, but optimized for neither).

In contrast to the Go implementation, they treat Tabulator (tab) characters that are part of leading white space (i.e., indentation) as identical to 8 space characters. Otherwise they implement the same algorithm as the Go implementation of section when invoked without options.

Treating a Tabulator character the same as 8 space characters is generally incorrect, but it works for the default indentation settings of the Vim editor.

My three simpler section implementations are available under the GNU All-Permissive License and can be found in my Single File Tools (SFT) collection:


Related Software

The section filter prints indentation based sections of text by matching a pattern. This complements existing tools that also print text based on matching a pattern, but use different strategies to decide which parts of the text to print.

Grep for Printing Lines

The grep filter selects only the individual lines matching a pattern. Some grep implementations, e.g., GNU grep, allow to also print a fixed number of lines preceding and/or following a matched line.

AWK for Printing Paragraphs

The AWK pattern scanning and processing language allows to print a paragraph containing a pattern match. In this context, a paragraph is a section of text delimited by empty lines. By setting AWK's record separator variable RS to the empty string, providing the pattern enclosed in slash characters, and omitting the action to use AWK's default action of printing the matched record, AWK prints the matched paragraphs:

awk -v RS='' /PATTERN/ [FILE...]


back to my homepage.