Bunch of changes, including some bpeg->bp renaming, and adding

visualizations

1 files changed, 209 insertions, 0 deletions

diff --git a/bp.1 b/bp.1
new file mode 100644
index 0000000..60a5e8f
--- /dev/null
+++ b/bp.1
@@ -0,0 +1,209 @@
+.\" 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-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 \-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 ..
+Any text \fBup-to-and-including\fR the following pattern, if any (multiline: \fB...\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
+\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 and \fI<pat2>\fR both match and have the exact
+same length. Pronounced \fI<pat1>\fB-assuming-it-equals-\fI<pat2>\fR
+
+.B \fI<pat1>\fB != \fI<pat2>\fR
+Will match only if \fI<pat1>\fR matches, but \fI<pat2>\fR doesn't also match with the
+same length. Pronounced \fI<pat1>\fB-unless-it-equals-\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)