From cf1e5d8f9c143bd129e3ce6b30f5c5614f59036a Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Mon, 10 May 2021 21:30:31 -0700 Subject: Improved docs --- bp.1 | 112 +++++++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 58 insertions(+), 54 deletions(-) diff --git a/bp.1 b/bp.1 index 5579644..7a0cc9e 100644 --- a/bp.1 +++ b/bp.1 @@ -90,116 +90,120 @@ 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 +A sequence: \fI\fR followed by \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 +A choice: \fI\fR, or if it doesn't match, then \fI\fR .B . -\fBAny\fR character (excluding newline) +Any character (excluding newline) .B ^ -\fBStart-of-a-line\fR +Start of a line .B ^^ -\fBStart-of-the-text\fR +Start of the text .B $ -\fBEnd-of-a-line\fR (does not include newline character) +End of a line (does not include newline character) .B $$ -\fBEnd-of-the-text\fR +End of the text .B _ -Zero or more \fBwhitespace\fR characters (specifically, spaces and tabs) +Zero or more whitespace characters (specifically, spaces and tabs) .B __ -Zero or more \fBwhitespace-or-newline\fR characters +Zero or more whitespace or newline characters .B | -A \fBword-boundary\fR +A word boundary .B `\fI\fR -The literal \fBcharacter-\fI\fR - -.B `\fI\fB-\fI\fR -The \fBcharacter-range-\fI\fB-to-\fI\fR +The literal character \fI\fR (e.g. \fB`@\fR matches the "@" character) .B `\fI\fB,\fI\fR -The literal \fBcharacter-\fI\fB-or-\fI\fR (can include arbitrarily many -comma-separated characters or character ranges). +The literal character \fI\fR or \fI\fR (e.g. \fB`a,e,i,o,u\fR) + +.B `\fI\fB-\fI\fR +The character range \fI\fR to \fI\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\fR -The \fBescape-sequence-\fI\fR (\fB\\n\fR, \fB\\x1F\fR, \fB\\033\fR, etc.) +An escape sequence (e.g. \fB\\n\fR, \fB\\x1F\fR, \fB\\033\fR, etc.) .B \\\\\fI\fB-\fI\fR -The \fBescape-sequence-range-\fI\fB-to-\fI\fR +An escape sequence range from \fI\fR to \fI\fR (e.g. \fB\\x00-x1F\fR) -.B \\\\\fIN\fR -A special case escape that matches a "nodent", one or more newlines followed by +.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\fR -\fBNot-\fI\fR +Not \fI\fR -.B [\fI\fR] -\fBMaybe-\fI\fR +.B [\fI\fB] +Maybe \fI\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) +Exactly \fIN\fR repetitions of \fI\fR (e.g. \fB5 `*\fR matches "*****") + +.B \fI\fB-\fI \fR +Between \fI\fR and \fI\fR repetitions of \fI\fR (e.g. \fB2-3 `*\fR) + +.B \fI\fB+ \fI\fR +At least \fI\fR or more repetitions of \fI\fR (e.g. \fB 2+ `*\fR) .B *\fI\fR -\fBsome-\fI\fBs\fR +Some \fI\fRs (zero or more) .B +\fI\fR -\fBat-least-one-\fI\fBs\fR +At least one \fI\fRs .B \fI\fR \fB%\fI \fR -\fI\fB-separated-by-\fI\fR (equivalent to \fI -\fB0+(\fI\fB)\fR) +\fI\fR separated by \fI\fR (e.g. \fB*word % `,\fR matches +zero or more comma-separated words) .B .. \fI\fR -Any text \fBup-to-and-including\fR \fI\fR (excluding newline) +Any text (except newlines) up to and including \fI\fR .B .. % \fI\fR \fI\fB -Any text \fBup-to-and-including\fR \fI\fR, but skipping over instances of \fI\fR. -E.g. \fB`"..`" % (`\\.) +Any text (except newlines) up to and including \fI\fR, skipping over +instances of \fI\fR (e.g. \fB`"..`" % (`\\.)\fR) .B <\fI\fR -\fBJust-after-\fI\fR (lookbehind) +Just after \fI\fR (lookbehind) .B >\fI\fR -\fBJust-before-\fI\fR (lookahead) +Just before \fI\fR (lookahead) .B @\fI\fR -\fBCapture-\fI\fR +Capture \fI\fR .B @\fI\fB=\fI\fR -\fBLet-\fI\fB-equal-\fI\fR (named capture) +Let \fI\fR equal \fI\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\fB => "\fI\fB" -\fBReplace-\fI\fB-with-\fI\fR. Note: \fI\fR should +.B \fI\fB => '\fI\fB' +Replace \fI\fR 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. +\fB@\fIfoo\fR (the capture named \fIfoo\fR in \fI\fR), etc. +For example, \fB@word _ @rest=(*word % _) => "@rest @1"\fR .B \fI\fB == \fI\fR -Will match only if \fI\fR matches and \fI\fR matches the text of \fI\fR's -match. Pronounced \fI\fB-if-it-matches-\fI\fR - -.B \fI\fB != \fI\fR -Will match only if \fI\fR matches and \fI\fR doesn't match the text of -\fI\fR's match. Pronounced \fI\fB-unless-it-matches-\fI\fR +Matches \fI\fR, if and only if \fI\fR also matches the text of +\fI\fR's match. (e.g. \fBword == ("foo_" *.)\fR matches words that start +with "foo_") .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 +Matches \fI\fR, if and only if \fI\fR does not match the text of +\fI\fR's match. (e.g. \fBword == ("foo_" *.)\fR matches words that do not +start with "foo_") -.B \fI\fB:\fI\fR -\fBDefine-\fI\fB-to-mean-\fI\fR (pattern definition) +.B \fI\fB: \fI\fR +Define \fI\fR to mean \fI\fR (pattern definition) .B # \fI\fR A line comment @@ -226,9 +230,9 @@ 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 +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 -- cgit v1.2.3