paul@2 | 1 | .TH "ASTGREP" "1" |
paul@2 | 2 | |
paul@2 | 3 | .\" Manual page prepared by: |
paul@2 | 4 | .\" |
paul@2 | 5 | .\" Paul Boddie <paul@boddie.org.uk> |
paul@2 | 6 | .\" |
paul@2 | 7 | .\" To view this file while editing, run it through groff: |
paul@2 | 8 | .\" groff -Tascii -man astgrep.1 | less |
paul@2 | 9 | |
paul@2 | 10 | .SH NAME |
paul@2 | 11 | astgrep \- grep/search through Python abstract syntax trees |
paul@2 | 12 | .SH SYNOPSIS |
paul@2 | 13 | .B astgrep |
paul@17 | 14 | [options] [ \-t TERM_TYPE ] [ \-e PATTERN ] [ \-r ] FILE... |
paul@2 | 15 | .SH DESCRIPTION |
paul@2 | 16 | \fBastgrep\fR is a program which searches through Python source files for |
paul@2 | 17 | textual information of a specific type. Instead of matching a search term or |
paul@2 | 18 | expression, \fIPATTERN\fR, to all text in a program, as \fBgrep\fR would do, |
paul@2 | 19 | \fBastgrep\fR matches only tokens in the program having a particular type, |
paul@2 | 20 | specified using \fITERM_TYPE\fR, such as names or constants. |
paul@2 | 21 | |
paul@17 | 22 | Like \fBgrep\fR, a collection of \fIFILE\fRs can be searched, and if the |
paul@17 | 23 | \fB\-r\fR option is specified, directory hierarchies can also be searched |
paul@17 | 24 | recursively, with the occurrences listed from each file successfully found |
paul@17 | 25 | and parsed. |
paul@2 | 26 | .SH COMMAND LINE OPTIONS |
paul@2 | 27 | .TP |
paul@2 | 28 | .BR \-n , " \-\-line-number" |
paul@2 | 29 | Show the line number of each match. |
paul@2 | 30 | .TP |
paul@2 | 31 | .BR \-p , " \-\-print-token" |
paul@2 | 32 | Show the matching token for each match. |
paul@2 | 33 | .TP |
paul@2 | 34 | \fB\-t\fR, \fB\-\-type\fR=\fITERM_TYPE\fR |
paul@17 | 35 | Indicate the type of token to be matched. If \fB*\fR is given, all term types |
paul@17 | 36 | are tested. |
paul@2 | 37 | .TP |
paul@2 | 38 | \fB\-e\fR, \fB\-\-regexp\fR=\fIPATTERN\fR |
paul@2 | 39 | Use \fIPATTERN\fR as the term to search for. |
paul@2 | 40 | .TP |
paul@17 | 41 | \fB\-r\fR, \fB\-R\fR, \fB\-\-recursive\fR |
paul@17 | 42 | Search Python files found within directories. |
paul@2 | 43 | .SH TERM TYPES |
paul@2 | 44 | Details of term types can be found in the "AST Nodes" section of the Python |
paul@2 | 45 | Library Reference or by using \fBpydoc\fR to inspect the node classes in the |
paul@2 | 46 | \fBcompiler.ast\fR Python module: |
paul@2 | 47 | .RS 4 |
paul@2 | 48 | .PP |
paul@2 | 49 | .PD 0 |
paul@2 | 50 | .B pydoc compiler.ast |
paul@2 | 51 | .RE |
paul@2 | 52 | .PD |
paul@2 | 53 | .SH EXAMPLES |
paul@2 | 54 | Search for classes whose name contains \fINode\fR in a particular file: |
paul@2 | 55 | .RS 4 |
paul@2 | 56 | .PP |
paul@2 | 57 | .PD 0 |
paul@2 | 58 | .B astgrep -t Class -e Node libxml2dom/__init__.py |
paul@2 | 59 | .RE |
paul@2 | 60 | .PD |
paul@2 | 61 | .PP |
paul@2 | 62 | Search for functions or methods whose name starts with \fIvisit\fR in a |
paul@2 | 63 | particular directory hierarchy, \fImicropython\fR, showing the name of the |
paul@2 | 64 | matching functions in the output: |
paul@2 | 65 | .RS 4 |
paul@2 | 66 | .PP |
paul@2 | 67 | .PD 0 |
paul@2 | 68 | .B astgrep -p -t Function -e '^visit' -r micropython |
paul@2 | 69 | .RE |
paul@2 | 70 | .PD |
paul@2 | 71 | .PP |
paul@2 | 72 | Search for accesses of attributes having the exact name \fI_node\fR in a |
paul@2 | 73 | particular directory hierarchy, \fIlibxml2dom\fR, showing the line number of |
paul@2 | 74 | each match in the output: |
paul@2 | 75 | .RS 4 |
paul@2 | 76 | .PP |
paul@2 | 77 | .PD 0 |
paul@2 | 78 | .B astgrep -n -t Getattr -e '^_node$' -r libxml2dom |
paul@2 | 79 | .RE |
paul@2 | 80 | .PD |
paul@17 | 81 | .SH LIMITATIONS |
paul@17 | 82 | \fBastgrep\fR does not attempt to search docstrings (since line number |
paul@17 | 83 | information is inaccurate for docstrings in abstract syntax trees) or comments |
paul@17 | 84 | (since the \fBcompiler\fR package only considers significant syntax when parsing |
paul@17 | 85 | programs). |
paul@17 | 86 | .PP |
paul@17 | 87 | \fBastgrep\fR cannot search syntactically incorrect programs (since the |
paul@17 | 88 | \fBcompiler\fR package will only return an abstract syntax tree for valid |
paul@17 | 89 | programs). |
paul@2 | 90 | .SH SEE ALSO |
paul@2 | 91 | .BR python (1), |
paul@17 | 92 | .BR pydoc (1), |
paul@2 | 93 | .BR grep (1) |
paul@2 | 94 | .PP |
paul@2 | 95 | astgrep |
paul@2 | 96 | .I http://www.boddie.org.uk/python/astgrep.html |
paul@2 | 97 | .PD |
paul@2 | 98 | .SH COPYRIGHT |
paul@2 | 99 | Copyright \(co 2008 Paul Boddie; License GNU GPL version 3 |