bp/bp.1

.\" Manpage for bp.
.\" Contact bruce@bruce-hill.com to correct errors or typos.
.TH man 1 "Sep 12, 2020" "0.1" "bp manual page"
.SH NAME
bp \- Bruce's Parsing Expression Grammar tool
.SH SYNOPSIS
.B bp
[\fI-h\fR|\fI--help\fR]
[\fI-v\fR|\fI--verbose\fR]
[\fI-e\fR|\fI--explain\fR]
[\fI-j\fR|\fI--json\fR]
[\fI-l\fR|\fI--list-files\fR]
[\fI-i\fR|\fI--ignore-case\fR]
[\fI-I\fR|\fI--inplace\fR]
[\fI-C\fR|\fI--confirm\fR]
[\fI-p\fR|\fI--pattern\fR \fI<pattern>\fR]
[\fI-r\fR|\fI--replace\fR \fI<replacement>\fR]
[\fI-s\fR|\fI--skip\fR \fI<skip pattern>\fR]
[\fI-g\fR|\fI--grammar\fR \fI<grammar file>\fR]
[\fI-G\fR|\fI--git\fR]
[\fI-c\fR|\fI--context\fR \fI<N>\fR]
\fI<pattern>\fR
[[--] \fI<input files...>\fR]

.SH DESCRIPTION
\fBbp\fR is a tool that matches parsing expression grammars using a custom syntax.

.SH OPTIONS
.B \-v\fR, \fB--verbose
Print debugging information.

.B \-e\fR, \fB--explain
Print a visual explanation of the matches.

.B \-j\fR, \fB--json
Print a JSON list of the matches. (Pairs with \fB--verbose\fR for more detail)

.B \-l\fR, \fB--list-files
Print only the names of files containing matches instead of the matches themselves.

.B \-i\fR, \fB--ignore-case
Perform pattern matching case-insensitively.

.B \-I\fR, \fB--inplace
Perform filtering or replacement in-place (i.e. overwrite files with new content).

.B \-C\fR, \fB--confirm
During in-place modification of a file, confirm before each modification.

.B \-r\fR, \fB--replace \fI<replacement>\fR
Replace all occurrences of the main pattern with the given string.

.B \-s\fR, \fB--skip \fI<skip pattern>\fR
While looking for matches, skip over \fB<skip pattern>\fR occurrences. This can
be useful for behavior like \fBbp -s string\fR (avoiding matches inside string
literals).

.B \-g\fR, \fB--grammar \fI<grammar file>\fR
Load the grammar from the given file.

.B \-G\fR, \fB--git\fR
Use \fBgit\fR to get a list of files. Remaining file arguments (if any) are
passed to \fBgit --ls-files\fR instead of treated as literal files.

.B \-c\fR, \fB--context \fI<N>\fR
The number of lines of context to print. If \fI<N>\fR is 0, print only the
exact text of the matches. If \fI<N>\fR is "all", print the entire file.
Otherwise, if \fI<N>\fR is a positive integer, print the whole line on which
matches occur, as well as the \fI<N-1>\fR lines before and after the match. The
default value for this argument is 1 (print whole lines where matches occur).

.B \-f\fR, \fB\--format \fIauto|fancy|plain\fR
Set the output format. \fIfancy\fR includes colors and line numbers,
\fIplain\fR includes neither, and \fIauto\fR (the default) uses \fIfancy\fR
formatting only when the output is a TTY.

.B \--help
Print the usage and exit.

.B <string-pattern>
The main pattern for bp to match. By default, this pattern is a string
pattern (see the \fBSTRING PATTERNS\fR section below).

.B <input files...>
The input files to search. If no input files are provided and data was
piped in, that data will be used instead. If neither are provided,
\fBbp\fR will search through all files in the current directory and
its subdirectories (recursively).

.SH PATTERNS
bp patterns are based off of a combination of Parsing Expression Grammars
and regular expression syntax. The syntax is designed to map closely to
verbal descriptions of the patterns, and prefix operators are preferred over
suffix operators (as is common in regex syntax).

Some patterns additionally have "multi-line" variants, which means that they
include the newline character.

.I <pat1> <pat2>
A sequence: \fI<pat1>\fR followed by \fI<pat2>\fR

.I <pat1> \fB/\fI <pat2>\fR
A choice: \fI<pat1>\fR, or if it doesn't match, then \fI<pat2>\fR

.B .
Any character (excluding newline)

.B ^
Start of a line

.B ^^
Start of the text

.B $
End of a line (does not include newline character)

.B $$
End of the text

.B _
Zero or more whitespace characters (specifically, spaces and tabs)

.B __
Zero or more whitespace or newline characters

.B "foo"
.B 'foo'
The literal string \fIstring\fR. Escape sequences are not allowed.

.B {foo}
The literal string \fIfoo\fR with word boundaries on either end. Escape sequences are not allowed.

.B `\fI<c>\fR
The literal character \fI<c>\fR (e.g. \fB`@\fR matches the "@" character)

.B `\fI<c1>\fB,\fI<c2>\fR
The literal character \fI<c1>\fR or \fI<c2>\fR (e.g. \fB`a,e,i,o,u\fR)

.B `\fI<c1>\fB-\fI<c2>\fR
The character range \fI<c1>\fR to \fI<c2>\fR (e.g. \fB`a-z\fR).
Multiple ranges can be combined with a comma (e.g. \fB`a-z,A-Z\fR).

.B \\\\\fI<esc>\fR
An escape sequence (e.g. \fB\\n\fR, \fB\\x1F\fR, \fB\\033\fR, etc.)

.B \\\\\fI<esc1>\fB-\fI<esc2>\fR
An escape sequence range from \fI<esc1>\fR to \fI<esc2>\fR (e.g. \fB\\x00-x1F\fR)

.B \\\\N
A special case escape that matches a "nodent": one or more newlines followed by
the same indentation that occurs on the current line.

.B !\fI<pat>\fR
Not \fI<pat>\fR

.B [\fI<pat>\fB]
Maybe \fI<pat>\fR

.B \fI<N> <pat>\fR
Exactly \fIN\fR repetitions of \fI<pat>\fR (e.g. \fB5 `*\fR matches "*****")

.B \fI<N>\fB-\fI<M> <pat>\fR
Between \fI<N>\fR and \fI<M>\fR repetitions of \fI<pat>\fR (e.g. \fB2-3 `*\fR)

.B \fI<N>\fB+ \fI<pat>\fR
At least \fI<N>\fR or more repetitions of \fI<pat>\fR (e.g. \fB 2+ `*\fR)

.B *\fI<pat>\fR
Some \fI<pat>\fRs (zero or more)

.B +\fI<pat>\fR
At least one \fI<pat>\fRs

.B \fI<repeating-pat>\fR \fB%\fI <sep>\fR
\fI<repeating-pat>\fR separated by \fI<sep>\fR (e.g. \fB*word % `,\fR matches
zero or more comma-separated words)

.B .. \fI<pat>\fR
Any text (except newlines) up to and including \fI<pat>\fR

.B .. % \fI<skip>\fR \fI<pat>\fB
Any text (except newlines) up to and including \fI<pat>\fR, skipping over
instances of \fI<skip>\fR (e.g. \fB`"..`" % (`\\.)\fR)

.B <\fI<pat>\fR
Just after \fI<pat>\fR (lookbehind)

.B >\fI<pat>\fR
Just before \fI<pat>\fR (lookahead)

.B @\fI<pat>\fR
Capture \fI<pat>\fR

.B @\fI<name>\fB=\fI<pat>\fR
Let \fI<name>\fR equal \fI<pat>\fR (named capture). Named captures can be used
as backreferences like so: \fB@foo=word `( foo `)\fR (matches "asdf(asdf)" or
"baz(baz)", but not "foo(baz)")

.B \fI<pat>\fB => '\fI<replacement>\fB'
Replace \fI<pat>\fR with \fI<replacement>\fR. Note: \fI<replacement>\fR should
be a string, and it may contain references to captured values: \fB@0\fR
(the whole of \fI<pat>\fR), \fB@1\fR (the first capture in \fI<pat>\fR),
\fB@\fIfoo\fR (the capture named \fIfoo\fR in \fI<pat>\fR), etc.
For example, \fB@word _ @rest=(*word % _) => "@rest @1"\fR

.B \fI<pat1>\fB == \fI<pat2>\fR
Matches \fI<pat1>\fR, if and only if \fI<pat2>\fR also matches the text of
\fI<pat1>\fR's match. (e.g. \fBword == ("foo_" *.)\fR matches words that start
with "foo_")

.B \fI<pat1>\fB != \fI<pat2>\fR
Matches \fI<pat1>\fR, if and only if \fI<pat2>\fR does not match the text of
\fI<pat1>\fR's match. (e.g. \fBword == ("foo_" *.)\fR matches words that do not
start with "foo_")

.B \fI<name>\fB: \fI<pat>\fR
Define \fI<name>\fR to mean \fI<pat>\fR (pattern definition)

.B # \fI<comment>\fR
A line comment

.SH STRING PATTERNS
One of the most common use cases for pattern matching tools is matching plain,
literal strings, or strings that are primarily plain strings, with one or two
patterns. \fBbp\fR is designed around this fact. The default mode for bp
patterns is "string pattern mode". In string pattern mode, all characters
are interpreted literally except for the backslash (\fB\\\fR), which may be
followed by a bp pattern (see the \fBPATTERNS\fR section above). Optionally,
the bp pattern may be terminated by a semicolon (\fB;\fR).

.SH EXAMPLES
.TP
.B
ls | bp foo
Find files containing the string "foo" (a string pattern)

.TP
.B
ls | bp '.c\\$' -r '.h'
Find files ending with ".c" and replace the extension with ".h"

.TP
.B
bp -p '{foobar} parens' my_file.py
Find the literal string \fB"foobar"\fR, assuming it's a complete word, followed
by a pair of matching parentheses in the file \fImy_file.py\fR

.TP
.B
bp -g html -p html-element -D matching-tag=a foo.html
Using the \fIhtml\fR grammar, find all \fIhtml-element\fRs matching
the tag \fIa\fR in the file \fIfoo.html\fR


.SH AUTHOR
Bruce Hill (bruce@bruce-hill.com)