236 lines
7.2 KiB
Groff
236 lines
7.2 KiB
Groff
.\" 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-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-g\fR|\fI--grammar\fR \fI<grammar file>\fR]
|
|
[\fI-G\fR|\fI--git\fR]
|
|
[\fI-c\fR|\fI--conntext\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 \-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 \--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 (excluding newline)
|
|
|
|
.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 |
|
|
A \fBword-boundary\fR
|
|
|
|
.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<c1>\fB,\fI<c2>\fR
|
|
The literal \fBcharacter-\fI<c1>\fB-or-\fI<c2>\fR (can include arbitrarily many
|
|
comma-separated characters or character ranges).
|
|
|
|
.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 \\\\\fIN\fR
|
|
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
|
|
\fBNot-\fI<pat>\fR
|
|
|
|
.B [\fI<pat>\fR]
|
|
\fBMaybe-\fI<pat>\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 (excluding newline)
|
|
|
|
.B .. % \fI<skip>\fR \fI<pat>\fB
|
|
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 \fI<name>\fB:\fI<pat>\fR
|
|
\fBDefine-\fI<name>\fB-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"==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)
|