Skip to content

JourneyCodesAyush/CPP-CLOC

BranchesTags

Repository files navigation

📚✨ CPP-CLOC - C++ Implementation of CLOC

Maintenance Mode

C++ License PRs Welcome

⚠️ Maintenance Mode:

CPP-CLOC has now shifted from active development to maintenance mode.

This project taught me more about C++ than any tutorial ever could. The original goals were:

  1. Re-implement cloc in a performant, statically typed language (the Python prototype didn’t cut it for performance).
  2. Learn how to structure and build a serious C++ project from scratch.

Both goals have been largely achieved. While CPP-CLOC is not “feature-complete” in the absolute sense, it is functionally solid for its intended purpose, and further polishing or adding new features would likely become an endless process. It’s now time to let the project rest.

⚡ Bug fixes and minor stability updates may still happen, but no new features are planned.

📑 Table of Contents

Current Version

v0.6.3 – Added release build mode with -O3 compiler optimization via Makefile. Debug build remains default. See CHANGELOG for details.

🌍 Overview

CPP-CLOC is a minimal C++ implementation of CLOC (Count Lines of Code) for multiple programming languages:

  • C, C++, C/C++ headers
  • Java
  • Python
  • HTML, MarkDown, CSS
  • JavaScript / TypeScript
  • Bash / PowerShell / Batch
  • Unknown (Not analyzed)

It provides fast, cross-platform analysis of code files, counting:

  • Lines of code
  • Comment lines
  • Blank lines
  • Total lines

⚡ Designed for speed and simplicity, written in modern C++.

⚡ Quick Install

⚠️ Requires C++17 compatible compiler and includes argparse.hpp header

Linux / macOS

git clone https://github.com/journeycodesayush/cpp-cloc.git
cd cpp-cloc
make
make RELEASE=1   # (optional) build optimized binary
./cloc_cpp <filename>

Windows (via Command Prompt / PowerShell)

git clone https://github.com/journeycodesayush/cpp-cloc.git
cd cpp-cloc
mkdir build
make RELEASE=1   # (optional) build optimized binary
.\cloc_cpp.exe <filename>

🛠️ Build Modes

CPP-CLOC supports two build modes via Makefile:

Debug Build (default)

Includes debug symbols and no optimization:

make

Release Build (optimized with -O3)

Enables compiler optimizations for improved performance:

make RELEASE=1

⚡ Use release builds for faster execution on large codebases.

💻 Usage

For better performance on large projects, build with make RELEASE=1 to enable compiler optimizations.

Run cpp-cloc on a directory or single file:

cloc_cpp src/

Optional output format flags (mutually exclusive):

cloc_cpp src/ --json
cloc_cpp src/ --csv
cloc_cpp src/ --xml

# Scan a directory and save results to a file
cloc_cpp ./src --output=results.txt

# Select output format and save to a file
cloc_cpp ./src --json --output=results.json

# Exclude directories by name
cloc_cpp ./src --exclude-dir=build,test

If no flag is provided, output is printed in the default table format.

Output includes:

  • Number of files analyzed
  • Total lines of code
  • Total comment lines
  • Total blank lines
  • Total lines overall

Languages supported:

Language Extension(s) Comment Style
C/C++ .c, .cpp, .h //, /* */
Java .java //, /* */
Python .py #, """ """
HTML .html <!-- -->
MarkDown .md <!-- -->
CSS .css /* */
JS/TS .js, .ts //, /* */
Bash .sh #
PowerShell .ps1 #
Batch .bat REM

Note

Only triple-double-quoted(""" """) strings are recognized for Python

📝 Examples

Directory Analysis

./cloc_cpp ./src

Output example:

C++ implementation of CLOC
Total time: 0.091 seconds
------------------------------------------------------------------------------
Language               Files     Code    Comments        Blank          Total
------------------------------------------------------------------------------
C++                        6      372           6           45            423
------------------------------------------------------------------------------
SUM                        6      372           6           45            423
------------------------------------------------------------------------------

Single File Analysis

./cloc_cpp ./src/main.cpp

⚙️ Features

  • ✅ Catch2-based analyzer test suite with invariant coverage
  • ✅ Supports multiple programming languages
  • ✅ Counts code, comments, blank lines, and total lines
  • ✅ Handles multi-line comments (/ ... /) and single-line comments
  • ✅ Cross-platform (Windows, Linux, macOS)
  • ✅ Lightweight and fast
  • ⚠️ Minimal dependency: requires argparse.hpp (included in include/argparse/)

Tests

Tests for the analyzer, the heart of CPP-CLOC, are available in tests/test_analyzer.cpp

Run tests with:

make test

📦 Dependencies

Build Dependencies

Library License Notes
argparse.hpp MIT Header-only C++17 library, included in include/argparse/, required to build the main binary

Test Dependencies

Library License Notes
Catch2 MIT Header-only, version 2.13.10, vendored in include/catch2/, used for analyzer tests only

⚠️ All external code is included as-is and is subject to its original license. CPP-CLOC itself is MIT-licensed.

⚠️ Known Limitations

  • Multi-line comments inside strings are intentionally treated as comments
printf("/*");
for(size_t i = 0; i <= 5; i++){
    printf("%d ",i);
}
printf("*/");

is counted as 2 lines of code and 3 lines of comment

  • comment markers inside strings are counted as comments
  • Does not detect nested comment blocks by design
  • Only triple-double-quoted (""" """) strings are treated as comments in Python; single-quote docstrings (''') are not recognized.

🧭 Design Philosophy

  • CPP-CLOC follows single-pass text-based analysis; it does not fully parse languages.
  • Some counting behaviors are cloc-aligned quirks, not bugs:
    • Lines with code + comments are counted as code.
    • Comment markers inside strings are treated as comments.
    • Embedded languages are not recognized.
    • Python docstrings are intentionally treated as comments.
  • Contributions may extend supported languages, improve performance, or refactor code, provided analyzer behavior and cloc-style counting semantics remain unchanged.

Important

cpp-cloc intentionally does not distinguish comment markers inside strings, docstrings, or other language constructs, because doing so would require partial parsing and violate its strictly text-based analysis model.

See PHILOSOPHY.md for a detailed guide.

📁 Project Structure

cpp-cloc/
├── include/           # Header files
├── src/               # Source files
│   ├── analyzer.cpp
│   ├── detector.cpp
│   ├── list_files.cpp
│   ├── middleware.cpp
│   ├── print.cpp
│   └── main.cpp
│
├── tests/     # Catch2 based analyzer tests
├── Makefile     # Build configuration
├── README.md
└── LICENSE

🧑‍💻 Development Guide

  • Analyzer: analyzer.cpp contains core logic
  • Stats: stats.cpp defines counting structures
  • String utilities: trimming, stripping whitespace
  • Languages supported: extend comment_syntax.hpp and update the detector.cpp and middleware.cpp to recognize the language

Tip: Add new languages by defining CommentSyntax and following the above instruction.

🤝 Contributing

  1. Fork the repo
git clone https://github.com/journeycodesayush/cpp-cloc.git
  1. Create a branch: feat/new-language or fix/bug
git switch -c feat/new-language
  1. Make changes & test locally
  2. Open a PR with clear description

Follow Angular Commit Message Convention:

feat(analyzer): add support for new language
fix(stats): correct blank line counting
docs(readme): update usage section
chore(build): update Makefile
refactor(analyzer): improve multiline comment detection

LICENSE

MIT License

Copyright (c) 2025 JourneyCodesAyush

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies
or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

📬 Author

Made with ❤️ by JourneyCodesAyush

About

A C++ implementation of CLOC for counting code, comments, and blank lines.

Topics

modern-cpp programming-languages cloc count-lines-of-code cpp-cloc

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

v0.6.3 Latest
Mar 22, 2026
+ 5 releases

Contributors

Languages