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