From eb329bdac9fe56d67cb130fb6cdbb28743c6504b Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Sat, 12 Dec 2020 16:31:53 -0800 Subject: Bunch of changes, including some bpeg->bp renaming, and adding visualizations --- bp.1 | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 bp.1 (limited to 'bp.1') 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\fR] +[\fI-p\fR|\fI--pattern\fR \fI\fR] +[\fI-P\fR|\fI--pattern-string\fR \fI\fR] +[\fI-d\fR|\fI--define\fR \fI\fR:\fI\fR] +[\fI-D\fR|\fI--define-string\fR \fI\fR:\fI\fR] +[\fI-r\fR|\fI--replace\fR \fI\fR] +[\fI-g\fR|\fI--grammar\fR \fI\fR] +[\fI-m\fR|\fI--mode\fR \fI\fR] +\fI\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\fR:\fI\fR +Define a grammar rule using a bp pattern. + +.B \-D\fR, \fB--define-string \fI\fR:\fI\fR +Define a grammar rule using a bp string pattern. + +.B \-r\fR, \fB--replace \fI\fR +Replace all occurrences of the main pattern with the given string. + +.B \-g\fR, \fB--grammar \fI\fR +Load the grammar from the given file. + +.B \-m\fR, \fB--mode \fI\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 +The main pattern for bp to match. By default, this pattern is a string +pattern (see the \fBSTRING PATTERNS\fR section below). + +.B +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 +A chain of patterns, pronounced \fI\fB-then-\fI\fR + +.I \fB/\fI \fR +A series of ordered choices (if one pattern matches, the following patterns +will not be attempted), pronounced \fI\fB-or-\fI\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\fR +The literal \fBcharacter-\fI\fR + +.B `\fI\fB-\fI\fR +The \fBcharacter-range-\fI\fB-to-\fI\fR + +.B \\\fI\fR +The \fBescape-sequence-\fI\fR (\fB\\n\fR, \fB\\x1F\fR, \fB\\033\fR, etc.) + +.B \\\fI\fB-\fI\fR +The \fBescape-sequence-range-\fI\fB-to-\fI\fR + +.B !\fI\fR +\fBNot-\fI\fR + +.B [\fI\fR] +\fBMaybe-\fI\fR + +.B \fI\fR? +\fI\fB-or-not\fR + +.B \fI \fR +.B \fI\fB-\fI \fR +.B \fI\fB+ \fI\fR +\fI\fB-to-\fI\fB-\fI\fBs\fR (repetitions of a pattern) + +.B *\fI\fR +\fBsome-\fI\fBs\fR + +.B +\fI\fR +\fBat-least-one-\fI\fBs\fR + +.B \fI\fR \fB%\fI \fR +\fI\fB-separated-by-\fI\fR (equivalent to \fI +\fB0+(\fI\fB)\fR) + +.B <\fI\fR +\fBJust-after-\fI\fR (lookbehind) + +.B >\fI\fR +\fBJust-before-\fI\fR (lookahead) + +.B @\fI\fR +\fBCapture-\fI\fR + +.B @\fI\fB=\fI\fR +\fBLet-\fI\fB-equal-\fI\fR (named capture) + +.B {\fI\fB => "\fI\fB"} +\fBReplace-\fI\fB-with-\fI\fR. Note: \fI\fR should +be a string, and it may contain references to captured values: \fB@0\fR +(the whole of \fI\fR), \fB@1\fR (the first capture in \fI\fR), +\fB@[\fIfoo\fR]\fR (the capture named \fIfoo\fR in \fI\fR), etc. + +.B \fI\fB == \fI\fR +Will match only if \fI\fR and \fI\fR both match and have the exact +same length. Pronounced \fI\fB-assuming-it-equals-\fI\fR + +.B \fI\fB != \fI\fR +Will match only if \fI\fR matches, but \fI\fR doesn't also match with the +same length. Pronounced \fI\fB-unless-it-equals-\fI\fR + +.B \fI\fB != \fI\fR +Will match only if \fI\fR and \fI\fR don't both match and have the +exact same length. Pronounced \fI\fB-assuming-it-doesn't-equal-\fI\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\fR )# +A block comment (can be nested) + +.B # \fI\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) -- cgit v1.2.3