Basic Usage¶
Baron provides two main functions:
parse
to transform a string into Baron’s FST;dumps
to transform the FST back into a string.
In [1]: from baron import parse, dumps
In [2]: source_code = "def f(x = 1):\n return x\n"
In [3]: fst = parse(source_code)
In [4]: generated_source_code = dumps(fst)
In [5]: generated_source_code
Out[5]: 'def f(x = 1):\n return x\n'
In [6]: source_code == generated_source_code
Out[6]: True
Like said in the introduction, the FST keeps the formatting unlike ASTs. Here the following 3 codes are equivalent but their formatting is different. Baron keeps the difference so when dumping back the FST, all the formatting is respected:
In [7]: dumps(parse("a = 1"))
Out[7]: 'a = 1'
In [8]: dumps(parse("a=1"))
Out[8]: 'a=1'
In [9]: dumps(parse("a = 1"))
Out[9]: 'a = 1'
Helpers¶
Baron also provides 3 helper functions show, show_file and show_node to explore the FST (in iPython for example). Those functions will print a formatted version of the FST so you can play with it to explore the FST and have an idea of what you are playing with.
Show¶
show
is used directly on a string:
In [10]: from baron.helpers import show
In [11]: show("a = 1")
[
{
"first_formatting": [
{
"type": "space",
"value": " "
}
],
"annotation_first_formatting": [],
"target": {
"type": "name",
"value": "a"
},
"annotation_second_formatting": [],
"operator": "",
"type": "assignment",
"annotation": {},
"value": {
"section": "number",
"type": "int",
"value": "1"
},
"second_formatting": [
{
"type": "space",
"value": " "
}
]
}
]
In [12]: show("a += b")
[
{
"first_formatting": [
{
"type": "space",
"value": " "
}
],
"annotation_first_formatting": [],
"target": {
"type": "name",
"value": "a"
},
"annotation_second_formatting": [],
"operator": "+",
"type": "assignment",
"annotation": {},
"value": {
"type": "name",
"value": "b"
},
"second_formatting": [
{
"type": "space",
"value": " "
}
]
}
]
Show_file¶
show_file
is used on a file path:
from baron.helpers import show_file
show_file("/path/to/a/file")
Show_node¶
show_node
is used on an already parsed string:
In [13]: from baron.helpers import show_node
In [14]: fst = parse("a = 1")
In [15]: show_node(fst)
[
{
"first_formatting": [
{
"type": "space",
"value": " "
}
],
"annotation_first_formatting": [],
"target": {
"type": "name",
"value": "a"
},
"annotation_second_formatting": [],
"operator": "",
"type": "assignment",
"annotation": {},
"value": {
"section": "number",
"type": "int",
"value": "1"
},
"second_formatting": [
{
"type": "space",
"value": " "
}
]
}
]
Under the hood, the FST is serialized into JSON so the helpers are simply encapsulating JSON pretty printers.