path: root/cgrep.roff

.TH CGREP "29 Feb 2020"
.SH Farzad Sadeghi
cgrep \ - grep for C-family source files

.SH NAME
.PP
cgrep

.SH SYNOPSIS
.PP
cgrep [options] [target]

.SH DESCRIPTION
.PP
\fBCgrep\fP [ OPTION ] [ TARGET ]
.br
Cgrep is a grep-like tool for the 
C-family languages. cgrep is written using clang's libtooling and as such 
will accept any option that clang accepts as well. Like clang,
cgrep will require you to have a compilation database. 
.PP
If you can build your sources without any specific command-line 
options, you can pass "--" as the last command-line option which
tells clang to try to build the source without a compilation database.
If you are using \fBmake\fP to build your code-base, you can use \fBBEAR(1)\fP
to generate a compilation database.


.SS Options
.PP
.TP
\fB-A=<int>\fP
How many lines after the matched line to print. Defaults to 0.

.TP
\fB-B=<int>\fP
Howm many lines before the matched line to print. Defaults to 0.

.TP
\fB-C=<int>\fP
Howm many lines before and after the matched line to print. Defaults to 0.

.TP
\fB--all\fP
Turns on all switches other than nameddecl.

.TP
\fB--awk\fP
Outputs locations in a gawk friendly format, not meant for human consumption. Defaults to false.

.TP
\fB--call\fP
Match function calls.

.TP
\fB--class\fP
Match class declarations.

.TP
\fB--cxxcall\fP
Matches member function calls.

.TP
\fB--cxxfield\fP
Match CXX field declarations.

.TP
\fB--crecord\fP
Match a record declarations.

.TP
\fB--declrefexpr\fP
Matches declrefexpr.
.br
\fIdeclreefexpr\fPs are any instance of a declaration that is being reference.
For example:
.br
uint_32 my_var;
.br
my_var = 10;
.br
In the second line, \fImy_var\fP is a declaration that is being referenced.
The rule applies for all named declarations.

.TP
\fB--extra-arg=<string>\fP
Additional argument to append to the compiler command line.
.br
This is the option to use when you want to pass extra arguments 
to cgrep. These would be the clang command line options.

.TP
\fB--extra-arg-before=<string>\fP
Additional argument to prepend to the compiler command line.
.br
This is the option to use when you want to pass extra arguments 
to cgrep. These would be the clang command line options.

.TP
\fB--func=<string>\fP
Match function declarations.
.br 
Function definitions are also function declarations so for a function
that has a declaration and a definition, cgrep will find two results.

.TP
\fB--header\fP
Match headers in header inclusions.

.TP
\fB--macro\fP
Match macro definitions.

.TP
\fB--mainfile\fP
Match identifiers in the main file only. Defaults to true.
.br
This option filters out matches found in the translation unit passed to
cgrep.

.TP
\fB--memfunc\fP
Match member function declarations.

.TP
\fB--cfield\fP
Match C field declations.

.TP
\fB--clangdiag\fP
Enables the normal diagnostics and fixits that you are used to see from clang.
By defualt this option is set to false. cgrep will use its own dignosticConsumer
when this option is set to false.

.TP
\fB--nameddecl\fP
Matches all named declarations.

.TP
\fB--nocolor\fP
The output will have no colors.
.br
The option is meant to be used for terminal emulators that don't support
ANSI escape sequences. This option disables the printing of any escape 
sequences.

.TP
\fB--nodecl\fP
Will not print out the declaration location for the matched identifier.

.TP
\fB--regex=<string>\fP
The regex to match against.One thing to keep in mind is that the regex will 
first pass through Cpp and then will pass through the regex engine. For 
example if you want to match for a literal '\' character, on the command 
line you will have to write '\\\\'. Cpp will remove the two backslashes 
deciding that they are both escape sequences and pass the regex engine 
the two backslashes, at which point the regex engine will understand 
the first backslash to be an escape sequence for the second backslash. 

.TP
\fB--struct\fP
Match structure declarations.

.TP
\fB--syshdr\fP
Match identifiers in system header as well. Defaults to false.
.br
This option filters out headers that are included using <>.

.TP
\fB--union\fP
Match union declarations.

.TP
\fB--var\fP
Match variable declarations.
.br
This switch will also match function parameters.

.SH EXAMPLE
.PP
.PP
As an example if you want to match for declrefexpr and function calls,
with no colors but with declarations present in the output you would write:
.br
cgrep --declrefexpr --call --nocolor --regex myawesomeregex myawesomecppfile.cpp
.br
In case you want to run cgrep without a compilation database, you can try:
.br
cgrep --declrefexpr --call --nocolor --regex myawesomeregex myawesomecppfile.cpp --
.PP
Passing the clang "std" option will let cgrep know which language the source file 
is going to be in. For example:
.br
cgrep --declrefexpr --call --regex jaja --extra-arg=--std=c++17 myfile.cpp
.br
The above command lets cgrep know that the input file is a Cpp source file.
.br
To do the same for a C file, just pass it the C standard your source file 
is following:
.br
cgrep --declrefexpr --call --regex jaja --extra-arg=--std=c11 myfile.c

.SH FILES
.PP
\fBcgrep\fP
The cgrep executable.

.SH "SEE ALSO"
.PP
BEAR(1)

.SH BUGS
.PP
cgrep \fBwill not\fP print out warnings and errors that your code might have
so please make sure clang can compile your code before attempting to use 
cgrep on your codebase.

.SH COPYRIGHT
.PP
Copyright (C) by Farzad Sadeghi
<https://github.com/bloodstalker/cgrep>

.SH "AUTHORS"
Farzad Sadeghi