Not Logged In

baron 0.1.3

Baron is a FST for Python, a Full Syntax Tree. By opposition to an AST whichdrops some syntax information in the process of its creation (like empty lines,comments, formatting), a FST keeps everything and guarantees the operation<code>ast\_to\_code(code\_to\_ast(source\_code)) == source\_code</code>.

Why is this important?======================

The usage of a FST might not be obvious at first sight so let's consider aseries of problems to illustrate it. Let's say that you want to write a program that will:

* rename a variable in a source file... without clashing with things that are not a variable (example: stuff inside a string)* inline a function/method* extract a function/method from a series of line of code* split a class into several classes* split a file into several modules* convert your whole code base from one ORM to another* do custom refactoring operation not implemented by IDE/rope* implement the class browser of smalltalk for python (the whole one where you can edit the code of the methods, not just showing code)

It is very likely that you will end up with the awkward feeling of writingclumpsy weak code that is very likely to break because you didn't though aboutall the annoying special cases and the formatting keeps bothering you. You mayend up playing with [ast.py](http://docs.python.org/2/library/ast.html) untilyou realize that it removes too much information to be suitable for thosesituations. You will probably ditch this task as simple too complicated andreally not worth the effort. You are missing a good abstraction that will takecare of all of the code structure and formatting for you so you can concentrateon your task.

The FST tries to be this abstraction. With it you can now work on a tree whichrepresents your code with its formatting. Moreover, since it is the exactrepresentation of your code, modifying it and converting it back to a stringwill give you back your code only modified where you have modified the tree.

Said in another way, what I'm trying to achieve with Baron is a paradigm change inwhich writing code that will modify code is now a realist task that is worththe price (I'm not saying a simple task, but a realist task, it's still acomplex task).

Other-----

Having a FST (or at least a good abstraction build on it) also makes it easierto do code generation and code analysis while those two operations are alreadyquite feasible (using [ast.py](http://docs.python.org/2/library/ast.html) forexample and a templating engine).

Some technical details======================

Baron produces a FST in the form of JSON (and by JSON I mean Python listsand dicts that can be dumped into JSON) for maximum interoperability.

Baron FST is quite similar to Python AST with some modifications to be moreintuitive to humans, since Python AST has been made for CPython interpreter.

Since playing directly with JSON is a bit raw I'm going to build an abstractionon top of it that will looks like BeautifulSoup/jQuery.

State of the project====================

Currently, Baron has been tested on the top 100 projects and the FST convertsback exactly into the original source code. So, it can be considered quitestable, but it is far away from having been battle tested.

Since the project is very young and no one is already using it except myproject, I'm open to modifications of the FST nodes but I will becomeconversative very fast once it gets some adoption and will probably accept tomodify it only once or two in the future with clear indications on how tomigrate.

**Baron is targeting python 2.[67]**. It has not been tested on python3 butshould be working for most part (except the new grammar like "yield from",obviously).

Installation============

pip install baron

Usage=====

```pythonfrom baron import parse, dumps

ast = parse(source_code_string)source_code_string == dumps(ast)```

Documentation=============

At the moment Baron doesn't have any documentation yet. The usage of the only2 functions provided by Baron is shown above. Apart from that, Baron provides 2helper functions to explore the FST (in iPython for example). Example:

```pythonfrom baron.helpers import show, show_file

show(string)show_file(file_path)```

Those 2 functions will print a formated version of the FST so you can play withit to explore the FST and have an idea of what you are playing with. Example:

Every node has a <code>type</code> key and all nodes of the same type share the samestructure (if you find that it is not the case, please open an issue). Andnearly all nodes have a <code>value</code> key (except the obvious one thatnever change like 'pass') that represents the data.

The <code>*\_formatting</code> value represents the formatting of the node. Theyare always around syntax element of Python, here, the "+" (the only exceptionto this rules are string since you code things like that in Python:<code>"a" ru'b' "cd" """ef"""</code>). The translationlooks like this: