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.
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
The section filter prints brief usage information when invoked
with either the
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.
A mirror of the development repository for section is available on GitHub.
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
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.
$ section clean Makefile clean: $(RM) $(BINARY) $(MANWEB) $(RM) -r $(SRCDIR) $(RM) $(wildcard tests/*.out) tests/tests.log distclean: clean $(RM) $(MAN) $(ARCHIVE) .PHONY: check clean installPlease note that the example output above may have been created with an older version of section, and thus older example input files. Attempts to reproduce the results with current section may result in different output.
section.gofile containing Go source code formatted with
$ section import section.go import ( "bufio" "errors" "flag" "fmt" "io" "log" "os" "regexp"Please note that the example output above may have been created with an older version of section, and thus older example input files. Attempts to reproduce the results with current section may result in different output.
$ man section | section -- --ignore --ignore-blank Ignore the indentation level of blank lines, so that sections always continue across them. -i, --ignore-case Ignore case distinctions for pattern matching, so that characters that differ only in case match each other.Please note that the example output above may have been created with an older version of section, and thus older example input files. Attempts to reproduce the results with current section may result in different output.
$ wget -q -O- 'https://www.rfc-editor.org/rfc/rfc8792.txt' | section --ignore-blank '^5\.' 5. Limitations 5.1. Not Recommended for Graphical Artwork While the solution presented in this document works on any kind of text-based content, it is most useful on content that represents source code (XML, JSON, etc.) or, more generally, on content that has not been laid out in two dimensions (e.g., diagrams). Fundamentally, the issue is whether the text content remains readable once folded. Text content that is unpredictable is especially susceptible to looking bad when folded; falling into this category are most Unified Modeling Language (UML) diagrams, YANG tree diagrams, and ASCII art in general. It is NOT RECOMMENDED to use the solution presented in this document on graphical artwork. 5.2. Doesn't Work as Well as Format-Specific Options The solution presented in this document works generically for all text-based content, as it only views content as plain text. However, various formats sometimes have built-in mechanisms that are better suited to prevent long lines. For instance, both the 'pyang' and 'yanglint' utilities [pyang] [yanglint] have the command-line option "tree-line-length", which can be used to indicate a desired maximum line length when generating YANG tree diagrams [RFC8340]. In another example, some source formats (e.g., YANG [RFC7950]) allow any quoted string to be broken up into substrings separated by a concatenation character (e.g., '+'), any of which can be on a different line. It is RECOMMENDED that authors do as much as possible within the selected format to avoid long lines.
As is the case with most software, section has bugs and limitations.
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.
The Go implementation of the section filter uses Go's
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.
The Go implementation of the section filter uses Go's
package, and thus inherits its strengths, weaknesses, and peculiarities.
flagpackage, 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 (
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:
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.
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.
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
awk -v RS='' /PATTERN/ [FILE...]
back to my homepage.