An educational compiler project built from scratch in C++20.
Overview · Status · Get started · Architecture · Repository structure · Roadmap · Contributing
Code2Pseudo is an open-source project that aims to translate C++ source code into readable, structured pseudocode.
The goal is to make program logic easier to follow, discuss, and learn—without requiring readers to understand every detail of the original syntax.
The project is being developed from the ground up as a small compiler pipeline. It currently focuses on source-file handling and the first steps of lexical analysis. Parsing, syntax-tree construction, and pseudocode generation are planned stages, not completed features.
The long-term goal is to make the same conversion engine available through multiple interfaces:
- CLI: the first interface, used to develop and validate the compiler core.
- Visual Studio Code extension: a planned editor integration for converting code without leaving VS Code.
- Online converter: a planned web interface where users can submit C++ code and view the generated pseudocode.
These interfaces depend on a reliable conversion engine. The VS Code extension and online converter are future goals; neither is available yet.
Project status: Early development. The current CLI is a development prototype, not yet a complete C++-to-pseudocode translator.
- Understand program logic: the long-term goal is to express code as clear pseudocode.
- Learn compiler construction: the project is developed incrementally, from reading source files to lexical and syntax analysis.
- Built from scratch: the core is implemented in C++ rather than relying on an existing code-to-pseudocode service.
- Open development: the architecture and roadmap are visible so others can follow the progress and contribute.
The repository currently includes:
| Component | Status | Details |
|---|---|---|
| CMake project setup | Implemented | C++20 executable configured with CMake. |
| Source-file reader | Implemented | Reads a source file into memory using the C++ standard library. |
| Lexer cursor | Implemented | Tracks the current position and reads characters from the source. |
| Identifier scanning | Prototype | Recognizes identifier-shaped sequences. Keyword classification is not complete yet. |
Token / TokenType definitions |
Initial design | Data structures are present; a complete token stream is still in progress. |
| Parser and AST | Planned | Not implemented yet. |
| Pseudocode generation | Planned | The end-to-end translation is not available yet. |
At this stage, the CLI accepts a C++ file path, reads the file, displays its contents, and prints identifier-shaped words found by the lexer prototype.
examples/cpp/test.cpp
#include <iostream>
int main (void){
int a =7;
return a;
}./build/code2pseudo examples/cpp/test.cppCode2Pseudo Compiler
Input file: examples/cpp/test.cpp
file content:
#include <iostream>
int main (void){
int a =7;
return a;
}
All the idfs of this program are:
Word: include
Word: iostream
Word: int
Word: main
Word: void
Word: int
Word: a
Word: return
Word: a
This output demonstrates source loading and basic identifier scanning. It is not the final pseudocode output. In particular, keywords are still reported as identifier-shaped words in this prototype.
The intended processing pipeline is shown below. Solid arrows represent the current prototype path; dashed arrows represent planned stages.
flowchart TD
A[ C++ source file ] --> B[ Source file reader ]
B --> C[ Lexer ]
C --> D[ Basic identifier scanning ]
D -. planned .-> E[ Token stream ]
E -. planned .-> F[ Parser ]
F -. planned .-> G[ Abstract syntax tree ]
G -. planned .-> H[ Pseudocode generator ]
H -. planned .-> I[ Structured pseudocode ]
flowchart TD
A["C++ Source File"] --> B["Source File Reader"]
B --> C["Lexer"]
C --> D["Identifier Scanning"]
D -.-> E["Token Stream - Planned"]
E -.-> F["Parser - Planned"]
F -.-> G["Abstract Syntax Tree - Planned"]
G -.-> H["Pseudocode Generator - Planned"]
H -.-> I["Pseudocode Output - Planned"]
The repository is organized into the compiler, language definitions, examples, documentation, and tests. The tree below follows the current workspace layout:
Code2Pseudo/
├── build/ # Local CMake build output (generated; do not commit)
├── compiler/
│ ├── app/
│ │ └── main.cpp # CLI entry point
│ ├── core/
│ │ ├── AST/ # Abstract syntax tree components
│ │ ├── errors/ # Compiler error types and reporting
│ │ └── source/
│ │ ├── sourceFile.cpp # Source-file reading implementation
│ │ └── sourceFile.hpp # SourceFile definition and declaration
│ ├── input/
│ │ ├── C/ # C language frontend (planned / in progress)
│ │ └── cpp/
│ │ ├── lexer/
│ │ │ ├── lexer.cpp # C++ lexical analysis implementation
│ │ │ ├── lexer.hpp # Lexer interface and state
│ │ │ ├── token.hpp # Token structure
│ │ │ └── tokenType.hpp # Token type enumeration
│ │ └── parser/ # C++ parser (planned / in progress)
│ ├── output/
│ │ └── pseudocode/ # Pseudocode generation output stage
│ └── validation/ # Validation utilities
├── docs/ # Project documentation
├── examples/
│ ├── cpp/
│ │ └── test.cpp # C++ input example
│ └── expected/ # Expected outputs for examples
├── language/
│ └── pseudocode/
│ ├── examples/ # Pseudocode examples
│ ├── grammar/ # Pseudocode grammar definitions
│ └── rules/ # Pseudocode writing and formatting rules
├── output/ # Generated output files
├── tests/
│ ├── integration/ # End-to-end pipeline tests
│ └── unit/ # Isolated component tests
├── .gitignore
├── CMakeLists.txt # CMake project configuration
├── LICENSE
├── README.md
└── SECURITY.md
| Path | Responsibility |
|---|---|
compiler/app/ |
Command-line application entry point. |
compiler/core/ |
Shared compiler components, including source handling, AST, and errors. |
compiler/input/cpp/lexer/ |
C++ lexical analysis: character navigation, identifier scanning, and token definitions. |
compiler/input/cpp/parser/ |
Reserved for parsing C++ tokens and building syntax structures. |
compiler/input/C/ |
Reserved for a future C frontend. |
compiler/output/pseudocode/ |
Pseudocode output stage. |
compiler/validation/ |
Validation-related compiler components. |
language/pseudocode/ |
Pseudocode examples, grammar, and language rules. |
examples/ |
Sample input programs and expected outputs. |
tests/ |
Unit and integration tests. |
docs/ |
Additional project documentation. |
output/ |
Generated files produced during local runs. |
Note:
build/is generated by CMake and should normally be ignored by Git. Empty placeholder directories may not appear in a GitHub checkout until they contain a tracked file (for example, a.gitkeep). The structure describes the current workspace organization; folders marked as planned or reserved are not claims of completed compiler functionality.
- A C++20-compatible compiler (for example, GCC or Clang).
- CMake 3.20 or newer.
- Git.
# 1. Clone the repository
git clone https://github.com/geniusinsanity/Code2Pseudo.git
# 2. Enter the project directory
cd Code2Pseudo
# 3. Configure the build
cmake -S . -B build
# 4. Compile
cmake --build build./build/code2pseudo examples/cpp/test.cppPass one source-file path as the command-line argument. The current prototype reads the file and reports the identifier-shaped sequences it finds.
Code2Pseudo is being built in small, understandable compiler stages:
- Load the source file.
- Track the current character in the input.
- Recognize identifiers and other lexical elements.
- Produce a stream of typed tokens.
- Parse tokens into a syntax tree.
- Generate structured pseudocode from the parsed representation.
The order matters: each stage provides the input needed by the next one.
Code2Pseudo is intended to grow beyond a command-line tool. The compiler core will be developed and tested first; additional interfaces can then reuse that core instead of implementing conversion logic separately.
flowchart TD
A[ C++ source code ] --> B[ Code2Pseudo conversion engine ]
B -. planned integration .-> C[ CLI ]
B -. planned integration .-> D[ Visual Studio Code extension ]
B -. planned integration .-> E[ Online converter ]
| Interface | Goal | Status |
|---|---|---|
| CLI | Run conversions from the terminal and support development/testing. | Prototype in development |
| VS Code extension | Select or open C++ code in VS Code and request pseudocode from the Code2Pseudo engine. | Planned |
| Online converter | Paste or upload C++ code in a web interface and view the generated pseudocode. | Planned |
The exact integration design for the editor and web interfaces will be decided after the compiler core and CLI are stable.
- Initial CMake project and C++20 setup
- Source-file loading
- Lexer cursor and character-navigation helpers
- Basic identifier scanning
- Keyword recognition
- Number scanning
- Operator and punctuation recognition
- Complete token generation
- Parser and abstract syntax tree (AST)
- Pseudocode generation for an initial C++ subset
- Stabilize the CLI and define a reusable conversion interface
- Build a Visual Studio Code extension powered by the Code2Pseudo engine
- Build an online C++-to-pseudocode converter
- Automated tests and broader examples
- Documentation of supported C++ syntax
Roadmap items may change as the architecture evolves. A checked item means the corresponding work is present in the repository; it does not imply full C++ language support.
Contributions, bug reports, and ideas are welcome.
- For bugs or feature ideas, open an issue.
- For larger changes, open an issue first so the approach can be discussed before implementation.
- Keep pull requests focused and include a clear description of the change.
- Update examples or documentation when behavior changes.
Please read the Security Policy before reporting a potential vulnerability.
Code2Pseudo is licensed under the Apache License 2.0.
If you find the project interesting, consider giving it a star on GitHub. Stars help other developers discover the repository and encourage continued development.