Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scala/scala-parser-combinators

simple combinator-based parsing for Scala. formerly part of the Scala standard library, now a separate community-maintained module
https://github.com/scala/scala-parser-combinators

parser-combinators parsing scala

Last synced: about 24 hours ago
JSON representation

simple combinator-based parsing for Scala. formerly part of the Scala standard library, now a separate community-maintained module

Awesome Lists containing this project

README

        

# scala-parser-combinators

[![build](https://github.com/scala/scala-parser-combinators/workflows/test/badge.svg)](https://github.com/scala/scala-parser-combinators/actions/workflows/ci.yml?query=branch%3Amain)
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3Aorg.scala-lang.modules%20a%3Ascala-parser-combinators_2.12)
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3Aorg.scala-lang.modules%20a%3Ascala-parser-combinators_2.13)
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3Aorg.scala-lang.modules%20a%3Ascala-parser-combinators_3)

This was originally part of the Scala standard library, but is now community-maintained, under the guidance of the Scala team at Akka (formerly Lightbend). If you are interested in joining the maintainers team, please contact [@Philippus](https://github.com/philippus) or [@SethTisue](https://github.com/SethTisue).

## Choosing a parsing library

This library's main strengths are:

* Stability. It's been around and in wide use for more than a decade.
* The codebase is modest in size and its internals are fairly simple.
* It's plain vanilla Scala. No macros, code generation, or other magic is involved.
* Multiple versions of Scala (2.12, 2.13, 3) are supported on all back ends (JVM, JS, Native).

Its main weaknesses are:

* Performance. If you are ingesting large amounts of data, you may want something faster.
* Minimal feature set.
* Inflexible, unstructured error reporting.

A number of other parsing libraries for Scala are available -- [see list on Scaladex](https://index.scala-lang.org/awesome/parsing?sort=stars).

## Documentation

* [Current API](https://javadoc.io/page/org.scala-lang.modules/scala-parser-combinators_2.13/latest/scala/util/parsing/combinator/index.html)
* The [Getting Started](docs/Getting_Started.md) guide
* A more complicated example, [Building a lexer and parser with Scala's Parser Combinators](https://enear.github.io/2016/03/31/parser-combinators/)
* "Combinator Parsing", chapter 33 of [_Programming in Scala, Third Edition_](http://www.artima.com/shop/programming_in_scala), shows how to apply this library to e.g. parsing of arithmetic expressions. The second half of the chapter examines how the library is implemented.

## Adding an sbt dependency

To depend on scala-parser-combinators in sbt, add something like this to your build.sbt:

```
libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" %
```

To support multiple Scala versions, see the example in [scala/scala-module-dependency-sample](https://github.com/scala/scala-module-dependency-sample).

### Scala.js and Scala Native

Scala-parser-combinators is also available for Scala.js and Scala Native:

```
libraryDependencies += "org.scala-lang.modules" %%% "scala-parser-combinators" %
```

## Example

```scala
import scala.util.parsing.combinator._

case class WordFreq(word: String, count: Int) {
override def toString = s"Word <$word> occurs with frequency $count"
}

class SimpleParser extends RegexParsers {
def word: Parser[String] = """[a-z]+""".r ^^ { _.toString }
def number: Parser[Int] = """(0|[1-9]\d*)""".r ^^ { _.toInt }
def freq: Parser[WordFreq] = word ~ number ^^ { case wd ~ fr => WordFreq(wd,fr) }
}

object TestSimpleParser extends SimpleParser {
def main(args: Array[String]) = {
parse(freq, "johnny 121") match {
case Success(matched,_) => println(matched)
case Failure(msg,_) => println(s"FAILURE: $msg")
case Error(msg,_) => println(s"ERROR: $msg")
}
}
}
```

For a detailed unpacking of this example see
[Getting Started](docs/Getting_Started.md).

## Contributing

* See the [Scala Developer Guidelines](https://github.com/scala/scala/blob/2.13.x/CONTRIBUTING.md) for general contributing guidelines
* Have a look at [existing issues](https://github.com/scala/scala-parser-combinators/issues)
* Ask questions and discuss [in GitHub Discussions](https://github.com/scala/scala-parser-combinators/discussions)
* Feel free to open draft pull requests with partially completed changes, to get feedback.