Bonsai
======
| Bonsai is an attempt to provide a miniature and refined representation
for the
| often cumbersome **syntax trees** and **program models**.
| This idea, of providing a *smaller tree* that 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 own
| 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``
compiler.
| At the moment of this writing, I am aware that these bindings are
incomplete
| in terms of AST information they provide.
| As this analysis tool developed, I realized that the C++ analysis
features
| are independent of ROS or any other framework, and that this kind of
tool
| might be useful for someone else, either as is, or as a starting point
for
| something else.
Features
--------
| Bonsai provides an interface to represent, analyse or manipulate
programs.
| The model it uses is abstract enough to serve as a basis for specific
language
| implementations, although it focuses more on
imperative/object-oriented
| languages for now.
What to expect from **bonsai**:
- classes for the different **entities of a program** (e.g. variables,
functions, etc.);
- extended classes for **specific programming languages** (only C++ for
now);
- **parser implementations**, able to take a file and produce a model
(e.g. ``clang`` for C++);
- extensible interface to **manipulate and query** the resulting model
(e.g. find calls for a function);
- a console script to use as a standalone application.
Installation
------------
| 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
| `clang.cindex bindings`_
| (``pip install clang``) to parse C++ files. Skip this if you want to
use
| 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
| repository.
.. code:: bash
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.
.. code:: bash
cd bonsai
python bonsai-runner.py <args>
You can also run it with the executable package syntax.
.. code:: bash
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.
.. code:: bash
[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
following.
.. code:: bash
python setup.py install
| After installation, you should be able to run the command ``bonsai``
in your terminal
| from anywhere.
Examples
--------
| 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
.. code:: python
parser = CppAstParser(workspace = "examples/cpp")
| access to the global (top level, or root) scope of the program, and
obtaining
| a pretty string representation of everything that goes in it
.. code:: python
parser.global_scope.pretty_str()
| getting a list of all references to variable ``a``, starting the
search from
| the top of the program (global scope)
.. code:: python
CodeQuery(parser.global_scope).all_references.where_name("a").get()
| and accessing diverse properties from the returned ``CodeReference``
objects,
| such as file line and column (``cppobj.line``, ``cppobj.column``), the
type of the
| object (``cppobj.result``), what is it a reference of
(``cppobj.reference``,
| in this case a ``CodeVariable``) and an attempt to interpret the
program and
| resolve the reference to a concrete value
(``resolve_reference(cppobj)``).
| Do note that **resolving 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 class
``C``
| and 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 0
| The pretty string representation, as seen, is a sort of
pseudo-language, inspired
| in 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 out
| the source for the abstract model and then the language-specific
| implementation of your choice.
.. _ROS: http://www.ros.org/
.. _clang.cindex bindings: https://github.com/llvm-mirror/clang/tree/master/bindings/python
.. _PyPi: https://pypi.python.org/pypi/bonsai-code
Raw data
{
"_id": null,
"home_page": "https://github.com/git-afsantos/bonsai",
"name": "bonsai-code",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "static-analysis ast parsing",
"author": "Andre Santos",
"author_email": "haros.framework@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cc/3c/95755937d4dbb6d493408e939445b86b675b623bc87cc4e72d67950523f3/bonsai-code-0.6.8.tar.gz",
"platform": "",
"description": "Bonsai\n======\n\n| Bonsai is an attempt to provide a miniature and refined representation\n for the\n| often cumbersome **syntax trees** and **program models**.\n| This idea, of providing a *smaller tree* that is more or less the same\n thing,\n| is where the name comes from.\n\n| This work started as part of an analysis tool that I am developing for\n my own\n| research. I am interested in analysing `ROS`_\n| robotics applications, which are often written in C++.\n| Since free C++ analysis tools are *rather scarce*, I tried\n| to come up with my own, using the Python bindings of the ``clang``\n compiler.\n| At the moment of this writing, I am aware that these bindings are\n incomplete\n| in terms of AST information they provide.\n\n| As this analysis tool developed, I realized that the C++ analysis\n features\n| are independent of ROS or any other framework, and that this kind of\n tool\n| might be useful for someone else, either as is, or as a starting point\n for\n| something else.\n\nFeatures\n--------\n\n| Bonsai provides an interface to represent, analyse or manipulate\n programs.\n| The model it uses is abstract enough to serve as a basis for specific\n language\n| implementations, although it focuses more on\n imperative/object-oriented\n| languages for now.\n\nWhat to expect from **bonsai**:\n\n- classes for the different **entities of a program** (e.g. variables,\n functions, etc.);\n- extended classes for **specific programming languages** (only C++ for\n now);\n- **parser implementations**, able to take a file and produce a model\n (e.g. ``clang`` for C++);\n- extensible interface to **manipulate and query** the resulting model\n (e.g. find calls for a function);\n- a console script to use as a standalone application.\n\nInstallation\n------------\n\n| Here are some instructions to help you get bonsai.\n| Bonsai has been tested with *Linux Ubuntu* and *Python 2.7*,\n| but the platform should not make much of a difference.\n| Dependencies are minimal, and depend on what you want to analyse.\n\n| Since at the moment there is only a single implementation for C++\n| using clang 3.8, you will need to install ``libclang`` and the\n| `clang.cindex bindings`_\n| (``pip install clang``) to parse C++ files. Skip this if you want to\n use\n| the library in any other way.\n\nMethod 1: Running Without Installation\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n| Open a terminal, and move to a directory where you want to clone this\n| repository.\n\n.. code:: bash\n\n git clone https://github.com/git-afsantos/bonsai.git\n\n| There is an executable script in the root of this repository to help\n you get started.\n| It allows you to run bonsai without installing it. Make sure that your\n terminal is at\n| the root of the repository.\n\n.. code:: bash\n\n cd bonsai\n python bonsai-runner.py <args>\n\nYou can also run it with the executable package syntax.\n\n.. code:: bash\n\n python -m bonsai <args>\n\nMethod 2: Installing Bonsai on Your Machine\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n| Bonsai is now available on `PyPi`_.\n| You can install it from source or from a wheel.\n\n.. code:: bash\n\n [sudo] pip install bonsai-code\n\n| The above command will install bonsai for you. Alternatively, download\n and extract its\n| source, move to the project\u2019s root directory, and then execute the\n following.\n\n.. code:: bash\n\n python setup.py install\n\n| After installation, you should be able to run the command ``bonsai``\n in your terminal\n| from anywhere.\n\nExamples\n--------\n\n| The ``cpp_example.py`` script at the root of this repository is a\n small example on\n| how to parse a C++ file and then find all references to a variable\n ``a`` in that file.\n| In it, you can see parser creation\n\n.. code:: python\n\n parser = CppAstParser(workspace = \"examples/cpp\")\n\n| access to the global (top level, or root) scope of the program, and\n obtaining\n| a pretty string representation of everything that goes in it\n\n.. code:: python\n\n parser.global_scope.pretty_str()\n\n| getting a list of all references to variable ``a``, starting the\n search from\n| the top of the program (global scope)\n\n.. code:: python\n\n CodeQuery(parser.global_scope).all_references.where_name(\"a\").get()\n\n| and accessing diverse properties from the returned ``CodeReference``\n objects,\n| such as file line and column (``cppobj.line``, ``cppobj.column``), the\n type of the\n| object (``cppobj.result``), what is it a reference of\n (``cppobj.reference``,\n| in this case a ``CodeVariable``) and an attempt to interpret the\n program and\n| resolve the reference to a concrete value\n (``resolve_reference(cppobj)``).\n\n| Do note that **resolving expressions and references is still\n experimental**,\n| and more often that not will not be able to produce anything useful.\n\n| This is the pretty string output for a program that defines a class\n ``C``\n| and a couple of functions.\n\n::\n\n class C:\n C():\n [declaration]\n\n void m(int a):\n [declaration]\n\n int x_ = None\n\n C():\n x_ = 0\n\n void m(int a):\n a = (a + 2) * 3\n this.x_ = a\n\n int main(int argc, char ** argv):\n C c = new C()\n c.m(42)\n C * c1 = new C()\n C * c2 = new C()\n new C()\n delete(c1)\n delete(c2)\n return 0\n\n| The pretty string representation, as seen, is a sort of\n pseudo-language, inspired\n| in the Python syntax, even though the parsed program is originally in\n C++.\n\n| For more details on what you can get from the various program\n entities, check out\n| the source for the abstract model and then the language-specific\n| implementation of your choice.\n\n.. _ROS: http://www.ros.org/\n.. _clang.cindex bindings: https://github.com/llvm-mirror/clang/tree/master/bindings/python\n.. _PyPi: https://pypi.python.org/pypi/bonsai-code\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Static analysis library.",
"version": "0.6.8",
"project_urls": {
"Homepage": "https://github.com/git-afsantos/bonsai"
},
"split_keywords": [
"static-analysis",
"ast",
"parsing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8730265c6fc841513cf36d17eaaf22cc149286c1901fb036dd381e021041602d",
"md5": "b7251e9e52a5cce6a2635a823cf2598d",
"sha256": "ca880e515a52ff823f5f7e79452867078270c81f18bc7616f4d038941a166d7b"
},
"downloads": -1,
"filename": "bonsai_code-0.6.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7251e9e52a5cce6a2635a823cf2598d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 52712,
"upload_time": "2021-10-08T16:23:33",
"upload_time_iso_8601": "2021-10-08T16:23:33.056974Z",
"url": "https://files.pythonhosted.org/packages/87/30/265c6fc841513cf36d17eaaf22cc149286c1901fb036dd381e021041602d/bonsai_code-0.6.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc3c95755937d4dbb6d493408e939445b86b675b623bc87cc4e72d67950523f3",
"md5": "31de73d3ac6989802624632ffabc2e9b",
"sha256": "6ef835e605bd8ac6cba9df68d0c9f176297027ccb277469ffb4baeea837a3602"
},
"downloads": -1,
"filename": "bonsai-code-0.6.8.tar.gz",
"has_sig": false,
"md5_digest": "31de73d3ac6989802624632ffabc2e9b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 42965,
"upload_time": "2021-10-08T16:23:35",
"upload_time_iso_8601": "2021-10-08T16:23:35.416885Z",
"url": "https://files.pythonhosted.org/packages/cc/3c/95755937d4dbb6d493408e939445b86b675b623bc87cc4e72d67950523f3/bonsai-code-0.6.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-10-08 16:23:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "git-afsantos",
"github_project": "bonsai",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bonsai-code"
}
JSON
