How stnuessl/rf works
Project Type and Purpose
• This is an open-source, command-line refactoring tool for C and C++ (“rf”).
• It parses, analyzes, and rewrites source code using Clang/LLVM libraries to perform safe, batchable renames of tags, functions, variables, macros, includes, namespaces, etc.
High-Level Architecture
At a glance, rf’s pipeline consists of:
· CLI Frontend
· Configuration & Database Loader
· Clang Tooling Integration
· Preprocessor Callback Dispatcher
· AST Consumer / Visitor
· Refactoring Action Factory → Refactorers
· Replacement Engine & File Writer
· Utilities & Tests
Major Components
A. CLI Frontend (src/main.cpp)
– Parses command-line flags (util/commandline.cpp/.hpp).
– Reads batch files or individual refactor commands.
B. Compilation Database Loader (util/CompilationDatabase.cpp/.hpp)
– Loads compile_commands.json for project compilation context.
C. Clang Tooling (libclang, llvm)
– Invokes ClangTool with file list and compiler arguments.
D. Preprocessor Callback Dispatcher (PPCallbackDispatcher.cpp/.hpp)
– Hooks into Clang’s preprocessor to track include directives and macros.
E. AST Processing
1. RefactoringASTConsumer (src/RefactoringASTConsumer.cpp/.hpp)
2. RefactoringASTVisitor (src/RefactoringASTVisitor.cpp/.hpp)
– Traverses AST nodes.
F. RefactoringActionFactory (src/RefactoringActionFactory.cpp/.hpp)
– Determines which specific Refactorer to apply based on CLI flags.
G. Refactorers (src/Refactorers/)
– Base classes (Refactorer.hpp) + specialized modules:
• NameRefactorer, FunctionRefactorer, MacroRefactorer, VariableRefactorer, EnumConstantRefactorer, IncludeRefactorer, NamespaceRefactorer, TagRefactorer
– Each encapsulates logic for finding and emitting replacements for its entity type.
H. Replacement Engine & Writer (inside Refactorers + Clang tooling)
– Collects clang::tooling::Replacements, applies them to the file system.
I. Utilities (src/util/)
– memory management, string utilities, YAML parsing (for batching), command-line helpers.
J. Testing Harness (test/)
– Sample code, YAML recipes, shell scripts to validate replacements.
K. Bash-Completion (bash-completion/rf)
– Auto-completion integration for the rf binary.
L. Project Scripts (utils/)
– fix-jcdb.py and make-jcdb.py to massage compile_commands.json for compatibility.
Component Relationships & Data Flow
1. User runs “rf” → main.cpp (CLI)
2. CLI invokes util/commandline → constructs RefactorOptions
3. CompilationDatabase reads compile_commands.json → supplies file list + flags
4. ClangTool is created with file list + flags
5. PPCallbackDispatcher registered → intercepts preprocessor events
6. RefactoringASTConsumer + RefactoringASTVisitor traverse each AST → emit callbacks
7. RefactoringActionFactory chooses and instantiates specific Refactorer(s)
8. Each Refactorer examines AST nodes, generates clang::tooling::Replacement
9. Collected replacements are applied and written back to disk
10. Optional: YAML util writes/reads batch definitions
11. Tests invoke rf against sample code and compare expected outputs
Architectural Patterns & Principles
• Visitor Pattern: ASTVisitor for decoupled traversal.
• Factory Pattern: RefactoringActionFactory to select Refactorer modules.
• Single-Responsibility: each Refactorer only handles one kind of renaming.
• Extensibility: new Refactorer modules can be added under src/Refactorers.
• Separation of Concerns: clear layers—CLI, config loader, Clang integration, AST processing, refactoring logic, utilities.
Technologies, Frameworks, Libraries
• C++11/14, STL
• LLVM / Clang Tooling & libclang
• YAML parser (custom in util/yaml.cpp)
• GNU Make (Makefile)
• Bash (completion script)
• Python (utils/fix-jcdb.py, utils/make-jcdb.py) for CI/setup support
Detail Level
• Every directory as a sub-component.
• How util/yaml plugs into batching feature.
• Test/ as a separate validation workflow.
• Do not over-abstract—display each Refactorer submodule if desired.