CppParser
=========

[![Build Status](https://github.com/satya-das/cppparser/actions/workflows/cmake-multi-platform.yml/badge.svg?event=push)](https://github.com/satya-das/cppparser/actions/workflows/cmake-multi-platform.yml)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/e2a1f6c5c8c149be816f1514ec491c98)](https://www.codacy.com/app/satya-das/cppparser?utm_source=github.com&utm_medium=referral&utm_content=satya-das/cppparser&utm_campaign=Badge_Grade)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An easy, fast, and robust library to parse C/C++ source code.

## Features
- No preprocessing; preprocessor constructs are part of the AST.
- Preserves most comments.
- Implemented from scratch using backtracking Yacc (BtYacc), so **no dependency on libclang**.
- Parses into a structured AST where file elements form a tree.
- Minimal dependencies: [Flex](https://github.com/westes/flex) on Unix-like platforms (Linux, macOS, etc.). On Windows, [Flex for Windows](http://gnuwin32.sourceforge.net/packages/flex.htm) is bundled for out-of-the-box usage.
- Supports parsing multi-file programs.

## Motivation
CppParser can be used to build tools that need parsing of C/C++ files.
It is also used to develop [cib](https://github.com/satya-das/cib/), which implements ABI-stable SDK architecture for C++ libraries.

## Example

To begin with we will see an example of parsing a hello-world program and see the AST that `CppParser` creates:
!INCLUDECODE "cppparser/test/unit/test-files/hello-world.cpp" (c++)

For the above hello-world program we can expect the generated AST to look like the following:
![AST for Hello World program](https://github.com/satya-das/cppparser/blob/master/cppparser/src/readme-assets/HelloWorldAST.svg "AST for Hello World program")

So, how do we access these elements of AST using `CppParser`?
Below is the program written as a unit test for validating the correctness of the generated AST:

!INCLUDECODE "cppparser/test/unit/test-hello-world.cpp" (c++)

**This example is real and is part of the actual unit tests for CppParser**.

For AST traversal, see [CppWriter](cppwriter), which uses the generated AST to create files.

## Building CppParser

### Get the source

```sh
git clone https://github.com/satya-das/CppParser.git
```

## Configure and build

```sh
cd cppparser
mkdir builds
cd builds
cmake ..
make
```

*Alternatively, if you prefer `Ninja` instead of `make`*:

```sh
cd cppparser
mkdir builds
cd builds
cmake -G Ninja ..
ninja
```

## For contributors who need to run tests

Make sure you also clone the dependencies. Run the following command in the parent directory of the root of `cppparser`.

```sh
git clone https://github.com/satya-das/common.git
```

After this command the `common` and `cppparser` folders should be side by side.

## Configure and run tests

```sh
cd cppparser
mkdir builds
cd builds
cmake -G Ninja .. -DCPPPARSER_BUILD_TESTS=ON
ninja && ninja test
```

Modify the command by removing `-G Ninja` if you prefer `make`.