Package: bonsai-code
Bonsai is an attempt to provide a miniature and refined representation
for theoften cumbersomesyntax treesandprogram models.This idea, of providing asmaller treethat is more or less the same
thing,is where the name comes from.This work started as part of an analysis tool that I am developing for
my ownresearch. I am interested in analysingROSrobotics applications, which are often written in C++.Since free C++ analysis tools arerather scarce, I triedto come up with my own, using the Python bindings of theclangcompiler.At the moment of this writing, I am aware that these bindings are
incompletein terms of AST information they provide.As this analysis tool developed, I realized that the C++ analysis
featuresare independent of ROS or any other framework, and that this kind of
toolmight be useful for someone else, either as is, or as a starting point
forsomething else.FeaturesBonsai provides an interface to represent, analyse or manipulate
programs.The model it uses is abstract enough to serve as a basis for specific
languageimplementations, although it focuses more on
imperative/object-orientedlanguages for now.What to expect frombonsai:classes for the differententities of a program(e.g. variables,
functions, etc.);extended classes forspecific programming languages(only C++ for
now);parser implementations, able to take a file and produce a model
(e.g.clangfor C++);extensible interface tomanipulate and querythe resulting model
(e.g. find calls for a function);a console script to use as a standalone application.InstallationHere are some instructions to help you get bonsai.Bonsai has been tested withLinux UbuntuandPython 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 installlibclangand theclang.cindex bindings(pip install clang) to parse C++ files. Skip this if you want to
usethe library in any other way.Method 1: Running Without InstallationOpen a terminal, and move to a directory where you want to clone thisrepository.gitclonehttps://github.com/git-afsantos/bonsai.gitThere 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 atthe root of the repository.cdbonsaipythonbonsai-runner.py<args>You can also run it with the executable package syntax.python-mbonsai<args>Method 2: Installing Bonsai on Your MachineBonsai is now available onPyPi.You can install it from source or from a wheel.[sudo]pipinstallbonsai-codeThe above command will install bonsai for you. Alternatively, download
and extract itssource, move to the project’s root directory, and then execute the
following.pythonsetup.pyinstallAfter installation, you should be able to run the commandbonsaiin your terminalfrom anywhere.ExamplesThecpp_example.pyscript at the root of this repository is a
small example onhow to parse a C++ file and then find all references to a variableain that file.In it, you can see parser creationparser=CppAstParser(workspace="examples/cpp")access to the global (top level, or root) scope of the program, and
obtaininga pretty string representation of everything that goes in itparser.global_scope.pretty_str()getting a list of all references to variablea, starting the
search fromthe top of the program (global scope)CodeQuery(parser.global_scope).all_references.where_name("a").get()and accessing diverse properties from the returnedCodeReferenceobjects,such as file line and column (cppobj.line,cppobj.column), the
type of theobject (cppobj.result), what is it a reference of
(cppobj.reference,in this case aCodeVariable) and an attempt to interpret the
program andresolve the reference to a concrete value
(resolve_reference(cppobj)).Do note thatresolving expressions and references is still
experimental,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 classCand a couple of functions.class C:
  C():
    [declaration]

  void m(int a):
    [declaration]

  int x_ = None

C():
  x_ = 0

void m(int a):
  a = (a + 2) * 3
  this.x_ = a

int main(int argc, char ** argv):
  C c = new C()
  c.m(42)
  C * c1 = new C()
  C * c2 = new C()
  new C()
  delete(c1)
  delete(c2)
  return 0The pretty string representation, as seen, is a sort of
pseudo-language, inspiredin the Python syntax, even though the parsed program is originally in
C++.For more details on what you can get from the various program
entities, check outthe source for the abstract model and then the language-specificimplementation of your choice.