path: root/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<pattern>\fR]
[\fI-p\fR|\fI--pattern\fR \fI<pattern>\fR]
[\fI-P\fR|\fI--pattern-string\fR \fI<string-pattern>\fR]
[\fI-d\fR|\fI--define\fR \fI<name>\fR:\fI<pattern>\fR]
[\fI-D\fR|\fI--define-string\fR \fI<name>\fR:\fI<string-pattern>\fR]
[\fI-r\fR|\fI--replace\fR \fI<replacement>\fR]
[\fI-g\fR|\fI--grammar\fR \fI<grammar file>\fR]
[\fI-m\fR|\fI--mode\fR \fI<mode>\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 \-d\fR, \fB--define \fI<name>\fR:\fI<pattern>\fR
Define a grammar rule using a bp pattern.

.B \-D\fR, \fB--define-string \fI<name>\fR:\fI<string-pattern>\fR
Define a grammar rule using a bp string pattern.

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

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

.B \-m\fR, \fB--mode \fI<mode>\fR
The mode to operate in. Options are: \fIfind-all\fR (the default),
\fIonly-matches\fR, \fIpattern\fR, \fIreplacement\fR, \fIreplace-all\fR
(implied by \fB--replace\fR), or any other grammar rule name.

.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 chain of patterns, pronounced \fI<pat1>\fB-then-\fI<pat2>\fR

.I <pat1> \fB/\fI <pat2>\fR
A series of ordered choices (if one pattern matches, the following patterns
will not be attempted), pronounced \fI<pat1>\fB-or-\fI<pat2>\fR

.B .
\fBAny\fR character (multiline: $.)

.B ^
\fBStart-of-a-line\fR

.B ^^
\fBStart-of-the-text\fR

.B $
\fBEnd-of-a-line\fR (does not include newline character)

.B $$
\fBEnd-of-the-text\fR

.B _
Zero or more \fBwhitespace\fR characters (specifically, spaces and tabs)

.B __
Zero or more \fBwhitespace-or-newline\fR characters

.B `\fI<c>\fR
The literal \fBcharacter-\fI<c>\fR

.B `\fI<c1>\fB-\fI<c2>\fR
The \fBcharacter-range-\fI<c1>\fB-to-\fI<c2>\fR

.B \\\\\fI<esc>\fR
The \fBescape-sequence-\fI<esc>\fR (\fB\\n\fR, \fB\\x1F\fR, \fB\\033\fR, etc.)

.B \\\\\fI<esc1>\fB-\fI<esc2>\fR
The \fBescape-sequence-range-\fI<esc1>\fB-to-\fI<esc2>\fR

.B !\fI<pat>\fR
\fBNot-\fI<pat>\fR

.B [\fI<pat>\fR]
\fBMaybe-\fI<pat>\fR

.B \fI<pat>\fR?
\fI<pat>\fB-or-not\fR

.B \fI<N> <pat>\fR
.B \fI<MIN>\fB-\fI<MAX> <pat>\fR
.B \fI<MIN>\fB+ \fI<pat>\fR
\fI<MIN>\fB-to-\fI<MAX>\fB-\fI<pat>\fBs\fR (repetitions of a pattern)

.B *\fI<pat>\fR
\fBsome-\fI<pat>\fBs\fR

.B +\fI<pat>\fR
\fBat-least-one-\fI<pat>\fBs\fR

.B \fI<repeating-pat>\fR \fB%\fI <sep>\fR
\fI<repeating-pat>\fB-separated-by-\fI<sep>\fR (equivalent to \fI<pat>
\fB0+(\fI<sep><pat>\fB)\fR)

.B .. \fI<pat>\fR
Any text \fBup-to-and-including\fR \fI<pat>\fR (multiline: \fB...\fR)

.B .. \fI<pat>\fB % \fI<skip>\fR
Any text \fBup-to-and-including\fR \fI<pat>\fR, but skipping over instances of \fI<skip>\fR.
E.g. \fB`"..`" % (`\\.)

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

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

.B @\fI<pat>\fR
\fBCapture-\fI<pat>\fR

.B @\fI<name>\fB=\fI<pat>\fR
\fBLet-\fI<name>\fB-equal-\fI<pat>\fR (named capture)

.B {\fI<pat>\fB => "\fI<replacement>\fB"}
\fBReplace-\fI<pat>\fB-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]\fR (the capture named \fIfoo\fR in \fI<pat>\fR), etc.

.B \fI<pat1>\fB == \fI<pat2>\fR
Will match only if \fI<pat1>\fR matches and \fI<pat2>\fR matches the text of \fI<pat1>\fR's
match. Pronounced \fI<pat1>\fB-if-it-matches-\fI<pat2>\fR

.B \fI<pat1>\fB != \fI<pat2>\fR
Will match only if \fI<pat1>\fR matches and \fI<pat2>\fR doesn't match the text of
\fI<pat1>\fR's match. Pronounced \fI<pat1>\fB-unless-it-matches-\fI<pat2>\fR

.B \fI<pat1>\fB != \fI<pat2>\fR
Will match only if \fI<pat1>\fR and \fI<pat2>\fR don't both match and have the
exact same length. Pronounced \fI<pat1>\fB-assuming-it-doesn't-equal-\fI<pat2>\fR

.B |
This pattern matches the indentation at the beginning of a line that has the
same indentation as the line before (or zero indentation on the first line).

.B #( \fI<comment>\fR )#
A block comment (can be nested)

.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"==id parens' my_file.py
Find the literal string \fB"foobar"\fR, assuming it's a complete identifier,
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)