jawn

## Jawn

"Jawn is for parsing jay-sawn."

### Origin

The term "jawn" comes from the Philadelphia area. It conveys about as
much information as "thing" does. I chose the name because I had moved
to Montreal so I was remembering Philly fondly. Also, there isn't a
better way to describe objects encoded in JSON than "things". Finally,
we get a catchy slogan.

Jawn was designed to parse JSON into an AST as quickly as possible.

![](https://github.com/typelevel/jawn/workflows/Scala/badge.svg)
[![Latest version](https://index.scala-lang.org/typelevel/jawn/jawn-parser/latest.svg?color=orange)](https://index.scala-lang.org/typelevel/jawn/jawn-parser)

### Overview

Jawn consists of three parts:

1. A fast, generic JSON parser (`jawn-parser`)
2. A small, somewhat anemic AST (`jawn-ast`)
3. A few helpful utilities (`jawn-util`)

Currently Jawn is competitive with the fastest Java JSON libraries
(GSON and Jackson) and in the author's benchmarks it often wins. It
seems to be faster than any other Scala parser that exists (as of July
2014).

Given the plethora of really nice JSON libraries for Scala, the
expectation is that you're probably here for `jawn-parser` or a
support package.

### Quick Start

Jawn supports Scala 2.12, 2.13, and 3 on the JVM and Scala.js.  Scala
2.12 and 2.13 are supported on Scala Native.

Here's a `build.sbt` snippet that shows you how to depend on Jawn in
your own sbt project:

```scala
// use this if you just want jawn's parser, and will implement your own facade
libraryDependencies += "org.typelevel" %% "jawn-parser" % "1.3.2"

// use this if you want jawn's parser and also jawn's ast
libraryDependencies += "org.typelevel" %% "jawn-ast" % "1.3.2"
```

If you want to use Jawn's parser with another project's AST, see the
"Supporting external ASTs with Jawn" section.  There are a few reasons
you might want to do this:

 * The library's built-in parser is significantly slower than Jawn's.
 * Jawn supports more input types (`ByteBuffer`, `File`, etc.).
 * You need asynchronous JSON parsing.

### Dependencies

*jawn-parser* has no dependencies other than Scala.

*jawn-ast* depends on *jawn-parser* but nothing else.

### Parsing

Jawn's parser is both fast and relatively featureful. Assuming you
want to get back an AST of type `J` and you have a `Facade[J]`
defined, you can use the following `parse` signatures:

```scala
Parser.parseUnsafe[J](String) → J
Parser.parseFromString[J](String) → Try[J]
Parser.parsefromPath[J](String) → Try[J]
Parser.parseFromFile[J](File) → Try[J]
Parser.parseFromChannel[J](ReadableByteChannel) → Try[J]
Parser.parseFromByteBuffer[J](ByteBuffer) → Try[J]
```

Jawn also supports asynchronous parsing, which allows users to feed
the parser with data as it is available. There are three modes:

* `SingleValue` waits to return a single `J` value once parsing is done.
* `UnwrapArray` if the top-level element is an array, return values as they become available. Set `multiValue` to `true`
if you want to support multipl