What is "incremental parser"?

Papa Carlo is the first Scala parsing library utilises incremental parsing approach.

An incremental parser is one that can recompile only those portions of a program that have been modified. Ordinary parsers must process entire source code file.

Therefore, when the end user makes small and frequent changes in the source code, an incremental parser indexes them immediately, without any significant time delays. Even if the program consists of thousands lines of code.

This property is very important in development of programming language analysis tools such as Integrated Development Environments that managing codebase in real time.

See the Demo Webapp of the incremental JSON parser based on Papa Carlo.

Typical use cases of incremental parser

• Language support plugins for code editors. For example full-featured Java IDE based on Sublime Text or VIM.
• Realtime code analysis tools. Imaging smart semantic Diff!
• Incremental compilers.
• Client-server compilation environment.

Papa Carlo features

• Syntax definition directly in the Scala code using library's API.
• Resulting parser builds and incrementally updates Abstract Syntax Tree.
• Error-recovery mechanism. The parser can build Parse Tree even if the source code contains syntax errors.
• Recursive descent parsing based on PEG grammars.
• Expressions parsing with Pratt algorithm and prepared primitives.

Contribution policy

Branch quick reference

• master: Primary GitHub branch that one should fork from and Pull Request to. This branch is for upcoming release commits. So all of the accepted Pull Request need to be tested at least with provided functional tests
• release: All release commits starting from the version 0.7.1
• development: This branch may contain intermediate development commits that are not well tested. It is used internally by the repository maintainers

Steps

1. Fork the master branch of the repository to your GitHub account.
2. Test your changes locally using sbt jvm/test command.
3. Commit your code changes and push them to your fork on GitHub.
4. Make a Pull Request back to the master branch of Eliah-Lakhin/papa-carlo.
5. Repository maintainers will review your Pull Request and merge in a few days.
6. New master branch will be built and the artifact will be pushed to Sonatype's Snapshot Repository.
7. Sooner or later master branch with your commits will be merged onto releases branch, and the new release artifact will appear in Maven Central. Also I'll add you to the Contributors List.

If you find something that needs to be reviewed and merged quickly(important bug or something that stucks your development process), please poke me by email/GoogleTalk: eliah.lakhin [at] gmail.com. Or by Skype: eliah.lakhin. I'll do the review as soon as possible.

License

Please read LICENSE for licensing details.

Related projects

• Papa Carlo's Aunt. ANTLR4 grammar port for Papa Carlo by Martin Mauch.
• Java Incremental Parser by Federico Tomassetti.
• Malvina programming language compiler.

Documentation

There is detailed tutorial on the project's website: http://lakhin.com/projects/papa-carlo/.

The tutorial is generated based mostly on materials from the wiki. The wiki is open for read/write access to everyone. And contribution is very welcome!

Users support forum: https://groups.google.com/forum/#!forum/papa-carlo.

Example parsers

• JSON parser.
• Calculator parser.

Another links

• Introduction blog post.
• Scala Days 2014 presentation by Sébastien Doeraene.
• Discussion on Reddit.
• Introduction article on Habrahabr in Russian.
• Approach brief description on Lambda the Ultimate.

If you have a project, or an article, or link to discussion related to the topic, please bring me a line to: eliah.lakhin [at] gmail.com. Or start a topic on the Forum. I will be glad to include it on the list.

Development status

Current version of the library is 0.7.0. The project is in Beta stage. All planned features are done and ready to use. Source code is covered by a number of functional tests.

I use Semantic Version policy v. 2.0 in naming project's versions. So the first stable release version will be "1.0.0".

Please see change log for details: CHANGES

JAR artifacts

• Release artifacts on Maven Central: http://central.maven.org/maven2/name/lakhin/eliah/projects/papacarlo/
• Snapshot and release artifacts on Sonatype: http://oss.sonatype.org/content/groups/public/name/lakhin/eliah/projects/papacarlo/

Build from sources

1. Install SBT. Version 1.4.4 is preferable.
2. Run sbt jvm/test to compile and run tests.
3. Run sbt jvm/packageBin to build JAR package. The JAR package can be found in the ./jvm/target/ directory.
4. Run sbt js-demo/fullLinkJS to build the JavaScript demo with Scala-JS. To start the demo, run a static HTTP web server with ./js/demo/ as a root.

For more details see doc/compile.md

Author

Ilya Lakhin (Илья Александрович Лахин), eliah.lakhin [at] gmail.com