{"id":18332636,"url":"https://github.com/circe/circe-yaml","last_synced_at":"2025-05-16T05:04:47.462Z","repository":{"id":37742780,"uuid":"60053206","full_name":"circe/circe-yaml","owner":"circe","description":"YAML parser for circe using SnakeYAML","archived":false,"fork":false,"pushed_at":"2025-05-12T17:31:38.000Z","size":480,"stargazers_count":142,"open_issues_count":29,"forks_count":49,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-12T18:25:53.431Z","etag":null,"topics":["circe","hacktoberfest","json","yaml"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/circe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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-05-31T02:45:32.000Z","updated_at":"2025-05-12T17:31:42.000Z","dependencies_parsed_at":"2023-02-14T12:02:17.824Z","dependency_job_id":"b8037e91-a426-409b-89bd-3705aae17f68","html_url":"https://github.com/circe/circe-yaml","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circe%2Fcirce-yaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circe%2Fcirce-yaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circe%2Fcirce-yaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circe%2Fcirce-yaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circe","download_url":"https://codeload.github.com/circe/circe-yaml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471060,"owners_count":22076585,"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":["circe","hacktoberfest","json","yaml"],"created_at":"2024-11-05T19:39:39.546Z","updated_at":"2025-05-16T05:04:47.443Z","avatar_url":"https://github.com/circe.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# circe-yaml\n\n[![Build status](https://github.com/circe/circe-yaml/workflows/Continuous%20Integration/badge.svg)](https://github.com/circe/circe-yaml/actions)\n[![Codecov status](https://codecov.io/gh/circe/circe-yaml/branch/master/graph/badge.svg)](https://codecov.io/gh/circe/circe-yaml)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.circe/circe-yaml_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.circe/circe-yaml_2.12)\n\nThis is a small library for parsing [YAML](https://yaml.org) into [circe](https://github.com/circe/circe)'s `Json` AST.\nYou can choose from multiple YAML backends:\n * `circe-yaml`: For parsing YAML 1.1 it uses [SnakeYAML](https://bitbucket.org/snakeyaml/snakeyaml).\n * `circe-yaml-v12`: For parsing YAML 1.2 it uses [snakeyaml-engine](https://bitbucket.org/snakeyaml/snakeyaml-engine).\n * `circe-yaml-scalayaml`: For parsing YAML on Scala.js or Scala Native (as well as Scala/JVM) it uses [scala-yaml](https://github.com/VirtusLab/scala-yaml).\n\n## Why?\n\nYAML is a useful data format for many purposes in which a more readable, less verbose document is desired.  One use\ncase, for example, is human-readable configuration files.\n\nSnakeYAML provides a Java API for parsing YAML and marshalling its structures into JVM classes. However, you might find \ncirce's way of marshalling into a Scala ADT preferable -- using compile-time specification or derivation rather than runtime \nreflection.  This enables you to parse YAML into `Json`, and use your existing (or circe's generic) `Decoder`s to perform \nthe ADT marshalling.  You can also use circe's `Encoder` to obtain a `Json`, and print that to YAML using this library.\n\n## Usage\n\nThe artifact is hosted by Sonatype, and release versions are synced to Maven Central:\n\nFor YAML 1.1\n```scala\nlibraryDependencies += \"io.circe\" %% \"circe-yaml\" % \"0.16.0\"\n```\nor for YAML 1.2\n```scala\nlibraryDependencies += \"io.circe\" %% \"circe-yaml-v12\" % \"0.16.0\"\n```\nor for YAML on Scala.js or Scala Native (as well as Scala/JVM)\n```scala\nlibraryDependencies += \"io.circe\" %% \"circe-yaml-scalayaml\" % \"0.16.0\"\n```\n\nSnapshot versions are available by adding the Sonatype Snapshots resolver:\n\n```scala\nresolvers ++= Resolver.sonatypeOssRepos(\"snapshots\")\n```\n\n### Parsing\nParsing is accomplished through the `io.circe.yaml.parser` package; its API is similar to that of `circe-parser`:\n\n```scala\nimport io.circe.yaml.parser\nval json: Either[ParsingFailure, Json] = parser.parse(yamlString)\n```\n\nAdditionally, there is a function for parsing multiple YAML documents from a single string:\n\n```scala\nval jsons: Stream[Either[ParsingFailure, Json]] = parser.parseDocuments(multiDocumentString)\n```\n\nBoth of these methods also support a \"streaming\" parse from a `java.io.Reader` – this is different from the behavior of \n`circe-streaming` (which supports fully asynchronous streaming parsing with iteratees) but does provide a convenient way to \nretrieve YAML from Java inputs:\n\n```scala\nval config = getClass.getClassLoader.getResourceAsStream(\"config.yml\")\nval json = parser.parse(new InputStreamReader(config))\n\nval configs = getClass.getClassLoader.getResourceAsStream(\"configs.yml\")\nval jsons = parser.parseDocuments(new InputStreamReader(configs))\n```\n\nOnce you've parsed to `Json`, usage is the same as circe. For example, if you have `circe-generic`, you can do:\n\n```scala\nimport cats.syntax.either._\nimport io.circe._\nimport io.circe.generic.auto._\nimport io.circe.yaml\n\ncase class Nested(one: String, two: BigDecimal)\ncase class Foo(foo: String, bar: Nested, baz: List[String])\n\nval json = yaml.parser.parse(\"\"\"\nfoo: Hello, World\nbar:\n    one: One Third\n    two: 33.333333\nbaz:\n    - Hello\n    - World\n\"\"\")\n\nval foo = json\n  .leftMap(err =\u003e err: Error)\n  .flatMap(_.as[Foo])\n  .valueOr(throw _)\n```\n\nOther features of YAML are supported:\n\n* Multiple documents - use `parseDocuments` rather than `parse` to obtain `Stream[Either[ParsingFailure, Json]]`\n* Streaming - use `parse(reader: Reader)` or `parseDocuments(reader: Reader)` to parse from a stream.  Not sure what\n  you'll get out of it.\n* References / aliases - The reference will be replaced with the complete structure of the alias\n* Explicit tags (on scalar values only) are handled by converting the tag/scalar pair into a singleton json object:\n  ```yaml\n  example: !foo bar\n  ```\n  becomes\n  ```json\n  { \"example\": { \"foo\": \"bar\" } }\n  ```\n\n### Printing\nThe package `io.circe.yaml.syntax` provides an enrichment to `Json` which supports easily serializing to YAML using common\noptions:\n\n```scala\nimport cats.syntax.either._\nimport io.circe.yaml._\nimport io.circe.yaml.syntax._\n\nval json = io.circe.jawn.parse(\"\"\"{\"foo\":\"bar\"}\"\"\").valueOr(throw _)\n\nprintln(json.asYaml.spaces2) // 2 spaces for each indent level\nprintln(json.asYaml.spaces4) // 4 spaces for each indent level\n```\n\nAdditionally, there is a class `io.circe.yaml.Printer` which (in similar fashion to circe's `Printer`) can be configured \nwith many options which control the `String` output. Its `pretty` method produces a `String` using the configured options:\n\n```\nio.circe.yaml.Printer(dropNullKeys = true, mappingStyle = Printer.FlowStyle.Block)\n  .pretty(json)\n```\n\n### Limitations\n\nOnly JSON-compatible YAML can be used, for obvious reasons:\n\n- Complex keys are not supported (only `String` keys)\n- Unlike YAML collections, a JSON array is not the same as a JSON object with integral keys (given the above, it would\n  be impossible).  So, a YAML mapping with integral keys will still be a JSON object, and the keys will be strings.\n\n## License\n\nThis is released under the Apache 2.0 license, as specified in [the LICENSE file](LICENSE).  It depends on both\ncirce and SnakeYAML, which each has its own license.  Consult those projects to learn about their licenses.\n\nThis library is neither endorsed by, nor affiliated with, SnakeYAML.\n\n## Contributing\nAs part of the [circe](https://github.com/circe/circe) community, circe-yaml supports the [Typelevel](http://typelevel.org/) [code of conduct](http://typelevel.org/conduct.html) and wants all of its channels (Gitter, GitHub, etc.) to be welcoming environments for everyone.\n\nPlease read the [circe Contributor's Guide](https://github.com/circe/circe/blob/master/CONTRIBUTING.md) for information about how to submit a pull request.\n\nThis circe community module is currently maintained by [Jeff May](https://github.com/jeffmay), [Darren Gibson](https://github.com/zarthross), and [Zach McCoy](https://github.com/zmccoy). It strives to conform as closely as possible to the style of circe itself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirce%2Fcirce-yaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirce%2Fcirce-yaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirce%2Fcirce-yaml/lists"}