Belr is Belledonne Communications' language recognition library, written in C++11.
It aims at parsing any input formatted according to a language defined by an ABNF grammar,
It parses text inputs formatted according to a language defined by an ABNF grammar,
such as the protocols standardized at IETF.
The recognized language elements are notified to the application through std::function provided to the parser by the application.
It drastically simplifies the writing of a parser, provided that the parsed language is defined with an *ABNF grammar[1]*.
The parser automaton is automatically generated by belr library, in memory, from the ABNF grammar text.
The application developer is responsible to connect belr's parser with its custom code through callbacks in order to get
notified of recognized language elements.
It is based on finite state machine theory and heavily relies on recursivity from an implementation standpoint.
The benefits of using belr are:
- belr is safe: no handly written code to parse the language. No buffer overflow. No mistakes in ABNF interpretation.
- belr saves time: a lot of human efforts are eliminated because the parser is automatically generated.
- belr saves space: belr does not generate source code files to insert in your build process either. The parser automaton is created at runtime, in memory.
- belr is fast, as it was around 50% faster on parsing SIP URIs compared to antlr/antlr3c.
- belr is flexible: you are free to design your parser API as you want, and simply connect the parser automaton with your API.
Then, from the grammar object returned, instanciate a parser object, by telling belr the name of a base class you have defined
to represent any element of the language. In the example below, it is called `SipElement`.
The parser object can be used as much time as needed. There is no no need to re-instanciate it each time you need to parse a new input !
```
ABNFGrammarBuilder builder;
Parser<shared_ptr<SipElement>> parser(grammar);
```
Now, you have to connect the parser with your own classes in order to have language elements filled into your objects.
```
parser.setHandler("SIP-URI", make_fn(&SipUri::create)) //tells that whenever a SIP-URI is found, a SipUri object must be created.
->setCollector("user", make_sfn(&SipUri::setUsername)) //tells that when a "user" field is found, SipUri::setUsername() is to be called for assigning the "user"
->setCollector("host", make_sfn(&SipUri::setHost)) //tells that when host is encountered, use SipUri::setHost() to assign it to our SipUri object.
