1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
# Getting started
Installation and your first steps with Arpeggio.
---
## Installation
Arpeggio is written in Python programming language and distributed with
setuptools support. If you have `pip` tool installed the most recent stable
version of Arpeggio can be installed form
[PyPI](https://pypi.python.org/pypi/Arpeggio/) with the following command:
```bash
$ pip install Arpeggio
```
To verify that you have installed Arpeggio correctly run the following command:
```bash
$ python -c 'import arpeggio'
```
If you get no error, Arpeggio is correctly installed.
To install Arpeggio for contribution see [here](about/contributing.md).
### Installing from source
If for some weird reason you don't have or don't want to use `pip` you can still
install Arpeggio from source.
To download source distribution do:
- download
$ wget https://github.com/textX/Arpeggio/archive/v1.1.tar.gz
- unpack
$ tar xzf v1.1.tar.gz
- install
$ cd Arpeggio-1.1
$ python setup.py install
## Quick start
Basic workflow in using Arpeggio goes like this:
**Write [a grammar](grammars.md)**. There are several ways to do that:
- [The canonical grammar format](grammars.md#grammars-written-in-python) uses
Python statements and expressions. Each rule is specified as Python function
which should return a data structure that defines the rule. For example a
grammar for simple calculator can be written as:
from arpeggio import Optional, ZeroOrMore, OneOrMore, EOF
from arpeggio import RegExMatch as _
def number(): return _(r'\d*\.\d*|\d+')
def factor(): return Optional(["+","-"]), [number, ("(", expression, ")")]
def term(): return factor, ZeroOrMore(["*","/"], factor)
def expression(): return term, ZeroOrMore(["+", "-"], term)
def calc(): return OneOrMore(expression), EOF
The python lists in the data structure represent ordered choices while the tuples represent sequences from the PEG.
For terminal matches use plain strings or regular expressions.
- The same grammar could also be written using [traditional textual PEG
syntax](grammars.md#grammars-written-in-peg-notations) like this:
number <- r'\d*\.\d*|\d+'; // this is a comment
factor <- ("+" / "-")? (number / "(" expression ")");
term <- factor (( "*" / "/") factor)*;
expression <- term (("+" / "-") term)*;
calc <- expression+ EOF;
- Or similar syntax but a little bit more readable like this:
number = r'\d*\.\d*|\d+' # this is a comment
factor = ("+" / "-")? (number / "(" expression ")")
term = factor (( "*" / "/") factor)*
expression = term (("+" / "-") term)*
calc = expression+ EOF
The second and third options are implemented using canonical first form.
Feel free to implement your own grammar syntax if you don't like these
(see modules `arpeggio.peg` and `arpeggio.cleanpeg`).
**Instantiate a parser**. Parser works as a grammar interpreter. There is no
code generation.
```python
from arpeggio import ParserPython
parser = ParserPython(calc) # calc is the root rule of your grammar
# Use param debug=True for verbose debugging
# messages and grammar and parse tree visualization
# using graphviz and dot
```
**Parse your inputs**
```python
parse_tree = parser.parse("-(4-1)*5+(2+4.67)+5.89/(.2+7)")
```
If parsing is successful (e.g. no syntax error if found) you get a [parse
tree](parse_trees.md).
**Analyze parse tree** directly or write a [visitor class](semantics.md) to
transform it to a more usable form.
For [textual PEG syntaxes](grammars.md#grammars-written-in-peg-notations)
instead of `ParserPyton` instantiate `ParserPEG` from `arpeggio.peg` or
`arpeggio.cleanpeg` modules. See examples how it is done.
To [debug your grammar](debugging.md) set `debug` parameter to `True`. A verbose
debug messages will be printed and a dot files will be generated for parser
model (grammar) and parse tree visualization.
Here is an image rendered using graphviz of parser model for `calc` grammar.
<a href="../images/calc_parser_model.dot.png" target="_blank"><img src="../images/calc_parser_model.dot.png" style="display:block; width: 15cm; margin-left:auto; margin-right:auto;"/></a>
And here is an image rendered for parse tree for the above parsed `calc` expression.
<a href="../images/calc_parse_tree.dot.png" target="_blank"><img src="../images/calc_parse_tree.dot.png"/></a>
## Read the tutorials
Next, you can read some of the step-by-step tutorials ([CSV](tutorials/csv), [BibTex](tutorials/bibtex),
[Calc](tutorials/calc)).
## Try the examples
Arpeggio comes with [a lot of
examples](https://github.com/textX/Arpeggio/tree/master/examples). To
install and play around with the examples follow the instructions from the [README
file](https://github.com/textX/Arpeggio/tree/master/examples).
|
