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 --- bpeg.1 | 209 ----------------------------------------------------------------- 1 file changed, 209 deletions(-) delete mode 100644 bpeg.1 (limited to 'bpeg.1') diff --git a/bpeg.1 b/bpeg.1 deleted file mode 100644 index 9f36e0b..0000000 --- a/bpeg.1 +++ /dev/null @@ -1,209 +0,0 @@ -.\" Manpage for bpeg. -.\" Contact bruce@bruce-hill.com to correct errors or typos. -.TH man 1 "Sep 12, 2020" "0.1" "bpeg manual page" -.SH NAME -bpeg \- Bruce's Parsing Expression Grammar tool -.SH SYNOPSIS -.B bpeg -[\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 -\fBbpeg\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 bpeg pattern. - -.B \-D\fR, \fB--define-string \fI\fR:\fI\fR -Define a grammar rule using a bpeg 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 bpeg 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, -\fBbpeg\fR will search through all files in the current directory and -its subdirectories (recursively). - -.SH PATTERNS -Bpeg 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. \fBbpeg\fR is designed around this fact. The default mode for bpeg -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 bpeg pattern (see the \fBPATTERNS\fR section above). Optionally, -the bpeg pattern may be terminated by a semicolon (\fB;\fR). - -.SH EXAMPLES -.TP -.B -ls | bpeg foo -Find files containing the string "foo" (a string pattern) - -.TP -.B -ls | bpeg '.c\\$' -r '.h' -Find files ending with ".c" and replace the extension with ".h" - -.TP -.B -bpeg -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 -bpeg -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