Introduction and Motivation
circe (pronounced SUR-see, or KEER-kee in classical Greek, or CHEER-chay in Ecclesiastical Latin) is a JSON library for Scala.
Why?
Dependencies and modularity
circe depends oncats, and thecore project has only one dependency (cats-core).
Other subprojects bring in dependencies onJawn (for parsing in thejawn subproject),Shapeless (for automatic codec derivation ingeneric), but it would be possible to replace the functionality provided by these subprojects with alternative implementations that use other libraries.
Parsing
circe doesn't include a JSON parser in thecore project, which is focused on the JSON AST, zippers, and codecs. Thejawn subproject provides support for parsing JSON via aJawn facade. Jawn is fast, cross-platform, and offers asynchronous parsing. Thecirce-jackson project supports usingJackson for both parsing and printing.
circe also provides aparser subproject that provides parsing support for Scala.js, with JVM parsing provided byio.circe.jawn and JavaScript parsing fromscalajs.js.JSON.
See theParsing page for more details.
Lenses
circe doesn't use or provide lenses in thecore project. This is related to the first point above, sinceMonocle has a Scalaz dependency, but we also feel that it simplifies the API. The 0.3.0 release addedan experimentaloptics subproject that provides Monocle lenses.
See theOptics page for more details.
Codec derivation
circe does not use macros or provide any kind of automatic derivation in thecore project. Insteadcirce includes a subproject (generic) that provides generic codec derivation usingShapeless.
This subproject provides fully automatic derivation of instances for case classes and sealed trait hierarchies. It also includes derivation of "incomplete" case class instances (see my recentblog post for details). Note that if you use-Ypartial-unification andauto, incomplete decoders will not work (see#724).
See theEncoding and Decoding page for more details.
Aliases
circe aims to simplify its API by using no operator aliases. This is largely a matter of personal taste, and may change in the future.
Testing
I'd like to provide more complete test coverage (in part viaDiscipline), but it's early days for this.
Performance
circe is developed with a focus on performance. See thePerformance page for details.
License
circe is licensed under theApache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.