{"id":18939310,"url":"https://github.com/belledonnecommunications/belr","last_synced_at":"2025-04-15T19:30:47.422Z","repository":{"id":88364254,"uuid":"50414269","full_name":"BelledonneCommunications/belr","owner":"BelledonneCommunications","description":"ABNF Parser - Linphone.org mirror for belr (git://git.linphone.org/belr.git)","archived":false,"fork":false,"pushed_at":"2024-11-29T21:57:10.000Z","size":485,"stargazers_count":8,"open_issues_count":0,"forks_count":6,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-29T01:13:13.695Z","etag":null,"topics":["abnf","c-plus-plus","parser"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BelledonneCommunications.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-26T08:19:56.000Z","updated_at":"2024-09-27T16:54:42.000Z","dependencies_parsed_at":"2023-11-27T06:33:37.108Z","dependency_job_id":"66d9030f-d45a-4d22-b3ec-36581b14c28a","html_url":"https://github.com/BelledonneCommunications/belr","commit_stats":null,"previous_names":[],"tags_count":217,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BelledonneCommunications%2Fbelr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BelledonneCommunications%2Fbelr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BelledonneCommunications%2Fbelr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BelledonneCommunications%2Fbelr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BelledonneCommunications","download_url":"https://codeload.github.com/BelledonneCommunications/belr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249138609,"owners_count":21218915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abnf","c-plus-plus","parser"],"created_at":"2024-11-08T12:17:07.449Z","updated_at":"2025-04-15T19:30:47.006Z","avatar_url":"https://github.com/BelledonneCommunications.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![pipeline status](https://gitlab.linphone.org/BC/public/belr/badges/master/pipeline.svg)](https://gitlab.linphone.org/BC/public/belr/commits/master)\n\nWhat is Belr\n============\n\nBelr is Belledonne Communications' language recognition library, written in C++11.\nIt parses text inputs formatted according to a language defined by an ABNF grammar,\nsuch as the protocols standardized at IETF.\n\nIt drastically simplifies the writing of a parser, provided that the parsed language is defined with an *ABNF grammar[1]*.\nThe parser automaton is automatically generated by belr library, in memory, from the ABNF grammar text.\nThe application developer is responsible to connect belr's parser with its custom code through callbacks in order to get\nnotified of recognized language elements.\n\nIt is based on finite state machine theory and heavily relies on recursivity from an implementation standpoint.\n\nThe benefits of using belr are:\n- belr is safe: no handly written code to parse the language. No buffer overflow. No mistakes in ABNF interpretation.\n- belr saves time: a lot of human efforts are eliminated because the parser is automatically generated.\n- 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.\n- belr is fast, as it was around 50% faster on parsing SIP URIs compared to antlr/antlr3c.\n- belr is flexible: you are free to design your parser API as you want, and simply connect the parser automaton with your API.\n\nLicense\n=======\n\nCopyright © [Belledonne Communications SARL](https://www.linphone.org), all rights reserved.\n\nBelr is dual licensed:\n- under a GNU GPLv3 license for free (see LICENSE.txt file for details)\n- under a proprietary license, for closed source projects. Contact sales@belledonne-communications.com for costs and other service information.\n\n\nHow it works\n============\n\nLet's take a very basic example to understand.\nYour application first needs to create a Grammar object from a text file contaning the ABNF grammar description:\n\n```\nABNFGrammarBuilder builder;\n// The grammar is constructed from sipgrammar.txt file, plus an additional built-in grammar called 'CoreRules',\n// which is used by almost every grammar.\nshared_ptr\u003cGrammar\u003e grammar=builder.createFromAbnfFile(\"sipgrammar.txt\", make_shared\u003cCoreRules\u003e());\n```\n\nThen, from the grammar object returned, instanciate a parser object, by telling belr the name of a base class you have defined\nto represent any element of the language. In the example below, it is called `SipElement`.\nThe 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 !\n\n```\nABNFGrammarBuilder builder;\nParser\u003cshared_ptr\u003cSipElement\u003e\u003e parser(grammar);\n```\n\nNow, you have to connect the parser with your own classes in order to have language elements filled into your objects.\n\n```\nparser.setHandler(\"SIP-URI\", make_fn(\u0026SipUri::create)) //tells that whenever a SIP-URI is found, a SipUri object must be created.\n\t\t-\u003esetCollector(\"user\", make_sfn(\u0026SipUri::setUsername)) //tells that when a \"user\" field is found, SipUri::setUsername() is to be called for assigning the \"user\"\n\t\t-\u003esetCollector(\"host\", make_sfn(\u0026SipUri::setHost)) //tells that when host is encountered, use SipUri::setHost() to assign it to our SipUri object.\n\t\t-\u003esetCollector(\"port\", make_sfn(\u0026SipUri::setPort));\n```\n\nHere, we have instructed our belr parser to invoke our `SipUri::create()` each time it recognizes a SIP-URI. This method must simply\nreturn a new `SipUri` instance.\nWe also told him, that each time the `user` part of a SIP URI is recognized, the `SipUri::setUsername(const std::string\u0026 user)` method must be called\nto fill the recognized user part into the created SipUri instance.\nSimilarly, we assign the `host` part with SipUri::setHost() method, and the `port` part with the SipUri::setPort() method.\n\nFinally, you can now parse a SIP-URI: \n\n```\nsize_t parsedSize;\nstring inputToParse = \"sip:bob@sip.example.org\";\nshared_ptr\u003cSipElement\u003e ret = parser.parseInput(\"SIP-URI\", inputToParse , \u0026parsedSize);\n//if the sip uri is recognized, the return value is non null and you can cast it into a SipUri object.\nif (ret){\n\tshared_ptr\u003cSipUri\u003e sipUri = dynamic_pointer_cast\u003cSipUri\u003e(ret);\n\t// Do what you want with the SipUri object...\n}\n```\n\nThe full example is in tools/belr-demo.cc.\n\nOne last thing to know. Grammar creation from text files requires many computations, which can slow down the startup of your application.\nFortunately, a solution exists: use the `belr-compiler` tool to generate a binary representation of the grammar, saved to disk and included \nas a resource in your application.\nYou can view the binary grammar as a kind of byte-code representing the language automaton.\nThen your application can simply instanciate the `Grammar` object by loading it from disk. It is hundred times faster.\n\nDependencies\n============\n\n- *bctoolbox[2]*: our portability layer\n\n\nBuild Belr\n==========\n\n\tcmake . -DCMAKE_INSTALL_PREFIX=\u003cprefix\u003e -DCMAKE_PREFIX_PATH=\u003csearch_prefixes\u003e\n\t\n\tmake\n\tmake install\n\n\nLimitations\n===========\n\nBelr doesn't handle non-deterministic ABNF grammars. For example:\n```\ntoken       =  1*(alphanum / \"-\" / \".\" / \"!\" / \"%\" / \"*\"\nmy-element  =  token \"!\" \n```\nThe problem of this grammar is that \"!\" is part of `token`, and also the termination character `my-element`.\nIt is non-deterministic: when the automaton finds a \"!\", it can recognize it as a `token`, or as the last \nelement of `my-element`.\n\nUnfortunately it is not so rare to encounter this kind of situation.\nBelr's current logic will be to include the \"!\" into `token`, all the time, because this is the first one that matches in the sequence.\n\nThe solution for this would be to have belr explore both possibilities, however this is not implemented as of today (2019-09-17).\nMost of time, a workaround exists by re-writing the problematic grammar rule in such a way that it is no longer this ambiguity.\n\n\nBuild options\n=============\n\n* `CMAKE_INSTALL_PREFIX=\u003cstring\u003e`: install prefix\n* `CMAKE_PREFIX_PATH=\u003cstring\u003e`: column-separated list of prefixes where to search for dependencies\n* `ENABLE_STRICT=NO`: build without strict compilation flags (-Wall -Werror)\n* `ENABLE_TOOLS=NO`: do not build tools (belr-demo, belr-parse)\n\n\nNote for packagers\n==================\n\nOur CMake scripts may automatically add some paths into research paths of generated binaries.\nTo ensure that the installed binaries are striped of any rpath, use `-DCMAKE_SKIP_INSTALL_RPATH=ON`\nwhile you invoke cmake.\n\nRpm packaging\nbelr can be generated with cmake3 using the following command:\nmkdir WORK\ncd WORK\ncmake3 ../\nmake package_source\nrpmbuild -ta --clean --rmsource --rmspec belr-\u003cversion\u003e-\u003crelease\u003e.tar.gz\n\n\n\n-----------------------\n\n* [1] https://tools.ietf.org/html/rfc5234\n* [2] git://git.linphone.org/bctoolbox.git or \u003chttp://www.linphone.org/releases/sources/bctoolbox\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbelledonnecommunications%2Fbelr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbelledonnecommunications%2Fbelr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbelledonnecommunications%2Fbelr/lists"}