Bonsai is an attempt to provide a miniature and refined representation
often cumbersome syntax trees and program models.
This idea, of providing a smaller tree that is more or less the same
is where the name comes from.
This work started as part of an analysis tool that I am developing for
research. I am interested in analysing ROS
robotics applications, which are often written in C++.
Since free C++ analysis tools are rather scarce, I tried
to come up with my own, using the Python bindings of the clang
At the moment of this writing, I am aware that these bindings are
in terms of AST information they provide.
As this analysis tool developed, I realized that the C++ analysis
are independent of ROS or any other framework, and that this kind of
might be useful for someone else, either as is, or as a starting point
Here are some instructions to help you get bonsai.
Bonsai has been tested with Linux Ubuntu and Python 2.7,
but the platform should not make much of a difference.
Dependencies are minimal, and depend on what you want to analyse.
Since at the moment there is only a single implementation for C++
using clang 3.8, you will need to install libclang and the
(pip install clang) to parse C++ files. Skip this if you want to
the library in any other way.
Method 1: Running Without Installation
Open a terminal, and move to a directory where you want to clone this
git clone https://github.com/git-afsantos/bonsai.git
There is an executable script in the root of this repository to help
you get started.
It allows you to run bonsai without installing it. Make sure that your
terminal is at
the root of the repository.
python bonsai-runner.py <args>
You can also run it with the executable package syntax.
python -m bonsai <args>
Method 2: Installing Bonsai on Your Machine
Bonsai is now available on PyPi
You can install it from source or from a wheel.
[sudo] pip install bonsai-code
The above command will install bonsai for you. Alternatively, download
and extract its
source, move to the project’s root directory, and then execute the
python setup.py install
After installation, you should be able to run the command bonsai
in your terminal
The cpp_example.py script at the root of this repository is a
small example on
how to parse a C++ file and then find all references to a variable
a in that file.
In it, you can see parser creation
parser = CppAstParser(workspace = "examples/cpp")
access to the global (top level, or root) scope of the program, and
a pretty string representation of everything that goes in it
getting a list of all references to variable a, starting the
the top of the program (global scope)
and accessing diverse properties from the returned CodeReference
such as file line and column (cppobj.line, cppobj.column), the
type of the
object (cppobj.result), what is it a reference of
in this case a CodeVariable) and an attempt to interpret the
resolve the reference to a concrete value
Do note that resolving expressions and references is still
and more often that not will not be able to produce anything useful.
This is the pretty string output for a program that defines a class
and a couple of functions.
void m(int a):
int x_ = None
x_ = 0
void m(int a):
a = (a + 2) * 3
this.x_ = a
int main(int argc, char ** argv):
C c = new C()
C * c1 = new C()
C * c2 = new C()
The pretty string representation, as seen, is a sort of
in the Python syntax, even though the parsed program is originally in
For more details on what you can get from the various program
entities, check out
the source for the abstract model and then the language-specific
implementation of your choice.