From ce6ef7f3eb05d6d28e5976910296c4dcce3d51a3 Mon Sep 17 00:00:00 2001 From: bloodstalker Date: Fri, 6 Mar 2020 20:57:38 +0330 Subject: updated the man and readme. --- README.md | 17 +++++--- cgrep.cpp | 1 - cgrep.roff | 139 +++++++++++++++++++++++++++++++++++++++++++++---------------- 3 files changed, 113 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 9c00d43..fbf487a 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,7 @@ # cgrep -`grep` for C/C++ source files. -Should be more or less fine for other C-family languages as well but I haven't tested for those since I don't use those. Let me know if you run into trouble using cgrep on those. -The goal is to make the options and features as similar to `grep` as possible for ease of use. +`grep` for C-family source files. ## Building @@ -49,12 +47,15 @@ If your build tool doesn't do that, you can just use [bear](https://github.com/r You can also skip the compilation database altogether passing cgrep `--` after the input file name which means you have chosen not to pass it anything. You can pass the options by hand since cgrep is a Clang instance so it recognizes every option clang has. -cgrep uses ANSI escape sequences for colors so your terminal should support those. +cgrep uses ANSI escape sequences for colors so your terminal should support those. In case your terminal does not support ANSI escape sequences, you can silence those using the `--nocolor` option. +By default, cgrep will print out the declaration location for a match. In case you don't want those in the output, you can pass cgrep the `--nodecl` switch. + +You can use `--extra-arg==--std=` to tell cgrep which C-family language the source file is supposed to be in. ## Options Here's an option list, though it might not be necessarily up-to-date. -For an up-to-date list, you can run `cgrep --help`. +For an up-to-date list, you can run `cgrep --help` or look at the man page. ```bash -A= - Same as grep, how many lines after the matched line to print. Defaults to 0. @@ -80,7 +81,7 @@ For an up-to-date list, you can run `cgrep --help`. -p= - Build path --regex= - The regex to match against. --struct - Match structures. - --syshdr - Match identifiers in system header as well. Defaults to true. + --syshdr - Match identifiers in system header as well. Defaults to false. --union - Match unions. --var - Match variables. ``` @@ -88,7 +89,11 @@ For an up-to-date list, you can run `cgrep --help`. `cgrep` is a clang tool, so it will accept all valid clang command line options. ## Known Issues +`cgrep` will not print out warnings or errors related to the source code so please make sure that clang can successfully build your file before running cgrep on it. ## License +cgrep is licensed under GPL-3.0. + + [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fbloodstalker%2Fcgrep.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fbloodstalker%2Fcgrep?ref=badge_large) diff --git a/cgrep.cpp b/cgrep.cpp index a764ba9..c654617 100644 --- a/cgrep.cpp +++ b/cgrep.cpp @@ -327,7 +327,6 @@ public: if (regex_handler(REGEX_PP(CO_REGEX), name)) { ast_type_traits::DynTypedNode DNode = ast_type_traits::DynTypedNode::create(*FD); - NamedDecl const *ND = DNode.get(); auto StartLocation = FD->getLocation(); auto EndLocation = StartLocation.getLocWithOffset(name.size() - 1); auto Range = SourceRange(StartLocation, EndLocation); diff --git a/cgrep.roff b/cgrep.roff index 8c48bee..a66b2e0 100644 --- a/cgrep.roff +++ b/cgrep.roff @@ -3,7 +3,6 @@ .SH Farzad Sadeghi cgrep \ - grep for C-family source files - .SH NAME .PP cgrep @@ -15,11 +14,10 @@ cgrep [options] [target] .SH DESCRIPTION .PP \fBCgrep\fP [ OPTION ] [ TARGET ] -\fIcgrep\fP cgrep is a grep-like tool for the -C-family languages. It supports a subset of grep -options to search through C-famlily source files. -cgrep is written using clang's libtooling and as such -will accept any option clang accepts as well. Like clang, +.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 @@ -28,105 +26,166 @@ 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=\fP -same as grep, how many lines after the matched line to print +How many lines after the matched line to print. Defaults to 0. .TP \fB-B=\fP -same as grep, howm many lines before the matched line to print +Howm many lines before the matched line to print. Defaults to 0. .TP \fB--all\fP -turns on all switches other than nameddecl +Turns on all switches other than nameddecl. .TP \fB--awk\fP -outputs location in a gawk freidnly format +Outputs locations in a gawk friendly format, not meant for human consumption. Defaults to false. .TP \fB--call\fP -match function calls only +Match function calls. .TP \fB--class\fP -match class declrations only +Match class declarations. .TP \fB--cxxcall\fP -match member function calls only +Matches member function calls. .TP \fB--declrefexpr\fP -matches declrefexpr - -.TP -\fB--dir=\fP -recursively goes through all the files and directories. assumes compilation databases are present for all source files. +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=\fP -Additional argument to append to the compiler command line +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=\fP -Additional argument to prepend to the compiler command line +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\fP -match functions only +\fB--func=\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 +Match headers in header inclusions. .TP \fB--macro\fP -match macro definitions +Match macro definitions. .TP \fB--mainfile\fP -match identifiers in the main file only +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 functions only +Match member function declarations. .TP \fB--memvar\fP -match member variables only +Match member variable declarations. .TP \fB--nameddecl\fP -matches all named declrations +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-p=\fP -Build path +\fB--nodecl\fP +Will not print out the declaration location for the matched identifier. .TP \fB--regex=\fP -the regex to match against +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 structures only +Match structure declarations. .TP \fB--syshdr\fP -match identifiers in system header as well +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 unions only +Match union declarations. .TP \fB--var\fP -match variables only +Match variable declarations. +.br +This switch will also match function parameters. -.SH "FILES" +.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. @@ -135,7 +194,13 @@ The cgrep executable. .PP BEAR(1) -.SH "COPYRIGHT" +.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 -- cgit v1.2.3