diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 117 |
1 files changed, 89 insertions, 28 deletions
@@ -1,25 +1,38 @@ -[](https://travis-ci.org/jodersky/yamlesque) - # yamlesque Pure Scala YAML parsing. -As the name suggests, "yam-el-esque" is a Scala implementation of the -most frequently used YAML features. It takes inspiration from -Spray-JSON and aims to provide an idiomatic API that is cross-platform -and has a minimal set of dependencies. +As the name suggests, "yam-el-esque" is a Scala implementation of the most +frequently used YAML features. It takes inspiration from [Haoyi Li's +ujson](http://www.lihaoyi.com/post/uJsonfastflexibleandintuitiveJSONforScala.html) +and aims to provide an idiomatic API that is cross-platform and has no +dependencies. ## Getting Started -Include yamlesque into a project. In sbt, this can be done with: -```scala -libraryDependencies += "io.crashbox" %% "yamlesque" % "<latest_tag>" -``` +Include yamlesque into a project. -### Parse some YAML -```scala -import yamlesque._ +- mill: + + ```scala + def ivyDeps = Agg(ivy"io.crashbox::yamlesque::<latest_tag>") + ``` + +- sbt: + + ```scala + libraryDependencies += "io.crashbox" %%% "yamlesque" % "<latest_tag>" + ``` +**Yamlesque is available for Scala 2.13, 2.12 and 2.11, including ScalaJS and +Native.** + +It should also work with Scala 2.10 and 2.9, although no pre-compiled libraries +are published for these versions. + +### Read Some YAML + +```scala val text = s"""|name: yamlesque |description: a YAML library for scala |authors: @@ -28,27 +41,75 @@ val text = s"""|name: yamlesque | - name: Another |""".stripMargin -// parse yaml to a type safe representation -val yaml = text.parseYaml +val yaml: yamlesque.Node = yamlesque.read(text) + +val id = yaml.obj("authors").arr(0).obj("id").str + +println(id) // == "jodersky" ``` -### Integration with Spray-JSON -*TODO* +### Write Some YAML -### Integration with Akka-HTTP -*TODO* +```scala +import yamlesque.{Arr, Num, Obj, Str} +val config = Obj( + "auth" -> Obj( + "username" -> Str("admin"), + "password" -> Str("guest") + ), + "interfaces" -> Arr( + Obj( + "address" -> Str("0.0.0.0"), + "port" -> Num(80) + ), + Obj( + "address" -> Str("0.0.0.0"), + "port" -> Num(443) + ) + ) +) + +val stringly = yamlesque.write(config) + +println(stringly) +``` + +will result in + +```yaml +auth: + username: admin + password: guest +interfaces: + - address: 0.0.0.0 + port: 80.0 + - address: 0.0.0.0 + port: 443.0 +``` -## YAML Conformance +## Official YAML Conformance Yamlesque does not strictly implement all features as defined in [YAML 1.2](http://yaml.org/spec/1.2/spec.html), however support should be -sufficient for most regular documents. Pull requests with additional -feature implementations are always welcome! +sufficient for most regular documents. + +Available features: + +- plain strings (i.e. scalars), including specialization to numbers, booleans + and null +- lists and maps +- quoted strings +- comments +- multiple documents (i.e. ---) + +Features which are currently not supported but for which support is planned: + +- verbatim blocks (i.e. | and >) (support is limited currently) +- flow-styles (aka inline JSON) + +Unsupported features with no planned implementation: -The current feature restrictions are: +- anchors and references +- tags -- always assumes utf-8 is used -- anchors and references are not supported -- tags are not supported -- flow-styles (aka inline JSON) aren't supported -- only single-line literals are allowed (no > or | blocks) +Pull requests with additional feature implementations are always welcome! |