- Notifications
You must be signed in to change notification settings - Fork19
fccf: A command-line tool that quickly searches through C/C++ source code in a directory based on a search string and prints relevant code snippets that match the query.
License
p-ranav/fccf
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
fccf is a command-line tool that quickly searches through C/C++ source code in a directory based on a search string and prints relevant code snippets that match the query.
- Quickly identifies source files that contain a search string.
- For each candidate source file, builds an abstract syntax tree (AST).
- Visits the nodes in the AST, looking for function declarations, classes, enums, variables etc., that match the user's request.
- Pretty-prints the identified snippet of source code to the terminal.
- MIT License
The following video showsfccf searching and finding snippets of code intorvalds/linux.
Searching.the.Linux.Kernel.Source.Tree.mp4
The following video showsfccf searching thefccf C++ source code.
Note that search results here include:
- Class declaration
- Functions and function templates
- Variable declarations, including lambda functions
Searching.the.fccf.Source.Tree.mp4
Provide an empty query to match any--flag, e.g., any enum declaration.
... or any class constructor
Use--for-statement to searchfor statements.fccf will try to findfor statements (including C++ rangedfor) that contain the query string.
Use the--include-expressions option to find expressions that match the query.
The following example showsfccf find calls toisdigit().
The following example showsfccf finding references to theclang_options variable.
Use the--using-declaration option to findusing declarations,using directives, and type alias declarations.
Use the--namespace-alias option to findnamespace aliases.
Use--throw-expression with a query to search for specificthrow expressions that contain the query string.
As presented earlier, an empty query here will attempt to match anythrow expression in the code base:
Buildfccf using CMake. For more details, seeBUILDING.md.
NOTE:fccf requireslibclang andLLVM installed.
# Install libclang and LLVM# sudo apt install libclang-dev llvmgit clone https://github.com/p-ranav/fccfcd fccf# Buildcmake -S. -B build -D CMAKE_BUILD_TYPE=Releasecmake --build build# Installsudo cmake --install build
foo@bar:~$fccf --helpUsage: fccf [--help] [--version] [--help] [--exact-match] [--json] [--filter VAR] [-j VAR] [--enum] [--struct] [--union] [--member-function] [--function] [--function-template] [-F] [--class] [--class-template] [--class-constructor] [--class-destructor] [-C] [--for-statement] [--namespace-alias] [--parameter-declaration] [--typedef] [--using-declaration] [--variable-declaration] [--verbose] [--include-expressions] [--static-cast] [--dynamic-cast] [--reinterpret-cast] [--const-cast] [-c] [--throw-expression] [--ignore-single-line-results] [--include-dir VAR]... [--language VAR] [--std VAR] [--no-color] query [path]...Positional arguments: query path [nargs: 0 or more]Optional arguments: -h, --help shows help message and exits -v, --version prints version information and exits -h, --help Shows help message and exits -E, --exact-match Only consider exact matches --json Print results in JSON format -f, --filter Only evaluate files that match filter pattern [nargs=0..1] [default: "*.*"] -j Number of threads [nargs=0..1] [default: 5] --enum Search for enum declaration --struct Search for struct declaration --union Search for union declaration --member-function Search for class member function declaration --function Search for function declaration --function-template Search for function template declaration -F Search for any function or function template or class member function --class Search for class declaration --class-template Search for class template declaration --class-constructor Search for class constructor declaration --class-destructor Search for class destructor declaration -C Search for any class or class template or struct --for-statement Search for `for` statement --namespace-alias Search for namespace alias --parameter-declaration Search for function or method parameter --typedef Search for typedef declaration --using-declaration Search for using declarations, using directives, and type alias declarations --variable-declaration Search for variable declaration --verbose Request verbose output --ie, --include-expressions Search for expressions that refer to some value or member, e.g., function, variable, or enumerator. --static-cast Search for static_cast --dynamic-cast Search for dynamic_cast --reinterpret-cast Search for reinterpret_cast --const-cast Search for const_cast -c Search for any static_cast, dynamic_cast, reinterpret_cast, orconst_cast expression --throw-expression Search for throw expression --isl, --ignore-single-line-results Ignore forward declarations, member function declarations, etc. -I, --include-dir Additional include directories [nargs=0..1] [default: {}] [may be repeated] -l, --language Language option used by clang [nargs=0..1] [default: "c++"] --std C++ standard to be used by clang [nargs=0..1] [default: "c++17"] --nc, --no-color Stops fccf from coloring the output
fccfdoes a recursive directory search for a needle in a haystack - likegreporripgrep- It uses anSSE2strstrSIMD algorithm (modified Rabin-Karp SIMD search; seehere) if possible to quickly find, in multiple threads, a subset of the source files in the directory that contain a needle.- For each candidate source file, it uses
libclangto parse the translation unit (build an abstract syntax tree). - Then it visits each child node in the AST, looking for specific node types, e.g.,
CXCursor_FunctionDeclfor function declarations. - Once the relevant nodes are identified, if the node's "spelling" (
libclangname for the node) matches the search query, then the source range of the AST node is identified - source range is the start and end index of the snippet of code in the buffer - Then, it pretty-prints this snippet of code. I have a simple lexer that tokenizes this code and prints colored output.
For all this to work, fccf first identifies candidate directories that contain header files, e.g., paths that end withinclude/. It then adds these paths to the clang options (before parsing the translation unit) as-Ifoo -Ibar/baz etc. Additionally, for each translation unit, the parent and grandparent paths are also added to the include directories for that unit in order to increase the likelihood of successful parsing.
Additional include directories can also be provided tofccf using the-I or--include-dir option. Using verbose output (--verbose), errors in the libclang parsing can be identified and fixes can be attempted (e.g., adding the right include directories so thatlibclang is happy).
To runfccf on thefccf source code without any libclang errors, I had to explicitly provide the include path from LLVM-12 like so:
foo@bar:~$fccf --verbose'lexer'. --include-dir /usr/lib/llvm-12/include/Checking ./source/lexer.cppChecking ./source/lexer.hppChecking ./source/searcher.cpp// ./source/lexer.hpp (Line: 14 to 40)class lexer{ std::string_view m_input; fmt::memory_buffer* m_out; std::size_t m_index {0}; bool m_is_stdout {true}; char previous() const; char current() const; char next() const; void move_forward(std::size_t n = 1); bool is_line_comment(); bool is_block_comment(); bool is_start_of_identifier(); bool is_start_of_string(); bool is_start_of_number(); void process_line_comment(); void process_block_comment(); bool process_identifier(bool maybe_class_or_struct = false); void process_string(); std::size_t get_number_of_characters(std::string_view str);public: void tokenize_and_pretty_print(std::string_view source, fmt::memory_buffer* out, bool is_stdout = true);}
About
fccf: A command-line tool that quickly searches through C/C++ source code in a directory based on a search string and prints relevant code snippets that match the query.