Merge pull request #92 from ufirstgroup/release-3.0.0

Prepare release 3.0.0

CHANGELOG.md

@@ -6,10 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
 
+## [3.0.0] - 2022-08-07
+
+**In this release we changed the way `DateTime` is encoded (see below). This can be a breaking change if you rely on the old date format with spaces. Because of this change, version 3.0.0 is now again compatible with Elixir 1.10**
+
 ### Changed
 
 - use `Enum.map_join/3` indead of `Enum.map/2` and `Enum.join/2` as it's more efficient according to credo recommendations
-- fix #87 - change the serialization of timestamps to use the canonical (iso8601) format, i.e. before: `2022-07-31 14:48:48.000000000 Z` and now: `"2022-07-31T14:48:48Z"`
+- Change the serialization of timestamps to use the canonical (iso8601) format, i.e. before: `2022-07-31 14:48:48.000000000 Z` and now: `"2022-07-31T14:48:48Z"` ([#87](https://github.com/ufirstgroup/ymlr/issues/87), [#90](https://github.com/ufirstgroup/ymlr/pull/90))
 
 ## [2.0.0] - 2021-04-02
 

README.md

@@ -11,30 +11,22 @@ ymlr - A YAML encoder for Elixir.
 [![Documentation](https://img.shields.io/badge/documentation-on%20hexdocs-green.svg)](https://hexdocs.pm/ymlr/)
 ![Hex.pm](https://img.shields.io/hexpm/l/ymlr.svg?style=flat)
 
-
 ## Installation
 
 The package can be installed by adding `ymlr` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
   [
-    {:ymlr, "~> 2.0"}
+    {:ymlr, "~> 3.0"}
   ]
 end
 ```
 
-## Versions and Support
-
-Version 2.0 does not support Elixir 1.10 anymore. However, for now all functionality is backported to version 1.x.
-
-| Ymlr Version | Supported Elixir Version |
-|:-------------:|:-------------:|
-| ~> 2.0 | ~> 1.11 |
-| ~> 1.0 | ~> 1.10 |
-
 ## Examples
 
+See The usage livebook `usage.livemd` for more detailed examples.
+
 ### Encode a single document - optionally with comments:
 
 ```elixir
@@ -63,7 +55,6 @@ Version 2.0 does not support Elixir 1.10 anymore. However, for now all functiona
     """
 ```
 
-
 ### Encode a multiple documents
 
 ```elixir

mix.exs

@@ -2,7 +2,7 @@ defmodule Ymlr.MixProject do
   use Mix.Project
 
   @source_url "https://github.com/ufirstgroup/ymlr"
-  @version "2.0.0"
+  @version "3.0.0"
 
   def project do
     [
@@ -20,7 +20,7 @@ defmodule Ymlr.MixProject do
       test_paths: ["lib"],
       docs: [
         main: "readme",
-        extras: ["README.md", "CHANGELOG.md"],
+        extras: ["README.md", "usage.livemd", "CHANGELOG.md"],
         source_ref: "v#{@version}",
         source_url: @source_url
       ]

usage.livemd

@@ -0,0 +1,239 @@
+<!-- livebook:{"persist_outputs":true} -->
+
+# Usage
+
+```elixir
+Mix.install([:kino, :ymlr])
+
+full = %{
+  "atom" => :ymlr,
+  "date" => ~D[2018-11-15],
+  "date_time" => ~U[2018-11-15 11:00:00Z],
+  "list" => ["item 1", "item 2", "item 3"],
+  "nested list" => [["item 1.1", "item 1.2"], ["item 2.1", "item 2.2", "item 2.3"]],
+  "nested map" => %{
+    "some" => %{
+      "nested" => ["data"]
+    }
+  },
+  "numbers" => %{
+    "float" => 3.14159265,
+    "hex" => 0x0B1010,
+    "int" => 123,
+    "oct" => 0o777
+  },
+  "numbers as strings" => %{
+    "float" => "3.14159265",
+    "hex" => "0x0b1010",
+    "int" => "123",
+    "oct" => "0o777"
+  },
+  "string" => "hello world",
+  "string (multiline)" => "hello\nworld"
+}
+
+simple_1 = %{"message" => "hello world"}
+simple_2 = %{"message" => "nice to be here"}
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+%{"message" => "nice to be here"}
+```
+
+## Encoding a single document
+
+Note: We defined document data as variables `full`, `simple_1` and `simple_2` in the setup block at the top of this livebook.
+
+<!-- livebook:{"reevaluate_automatically":true} -->
+
+```elixir
+full
+|> Ymlr.document!()
+|> IO.puts()
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+---
+atom: ymlr
+date:
+  2018-11-15
+date_time:
+  2018-11-15 11:00:00.000000000 Z
+list:
+  - item 1
+  - item 2
+  - item 3
+nested list:
+  - - item 1.1
+    - item 1.2
+  - - item 2.1
+    - item 2.2
+    - item 2.3
+nested map:
+  some:
+    nested:
+      - data
+numbers:
+  float: 3.14159265
+  hex: 725008
+  int: 123
+  oct: 511
+numbers as strings:
+  float: '3.14159265'
+  hex: '0x0b1010'
+  int: '123'
+  oct: '0o777'
+string: hello world
+string (multiline): |-
+  hello
+  world
+
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+:ok
+```
+
+<!-- livebook:{"reevaluate_automatically":true} -->
+
+```elixir
+simple_1
+|> Ymlr.document()
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+{:ok, "---\nmessage: hello world\n"}
+```
+
+## Encoding multiple documents
+
+```elixir
+[simple_1, simple_2]
+|> Ymlr.documents!()
+|> IO.puts()
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+---
+message: hello world
+
+---
+message: nice to be here
+
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+:ok
+```
+
+<!-- livebook:{"reevaluate_automatically":true} -->
+
+```elixir
+[simple_1, simple_2]
+|> Ymlr.documents()
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+{:ok, "---\nmessage: hello world\n\n---\nmessage: nice to be here\n"}
+```
+
+## Adding comments
+
+To add a comment at the top of the YAML document, pass a tuple in the form `{comment, document}` to any of the functions.
+
+<!-- livebook:{"reevaluate_automatically":true} -->
+
+```elixir
+{"Single comment", simple_1}
+|> Ymlr.document!()
+|> IO.puts()
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+---
+# Single comment
+message: hello world
+
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+:ok
+```
+
+The first element of the tuple can be a list of comments:
+
+<!-- livebook:{"reevaluate_automatically":true} -->
+
+```elixir
+{["First comment", "Second Comment", "Third Comment"], simple_1}
+|> Ymlr.document!()
+|> IO.puts()
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+---
+# First comment
+# Second Comment
+# Third Comment
+message: hello world
+
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+:ok
+```
+
+Multiple documents with comments:
+
+```elixir
+[
+  {["First doc, first comment", "First doc, second Comment", "First doc,  Comment"], simple_1},
+  {["Second doc, first comment", "Second doc, second comment"], simple_2}
+]
+|> Ymlr.documents!()
+|> IO.puts()
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+---
+# First doc, first comment
+# First doc, second Comment
+# First doc,  Comment
+message: hello world
+
+---
+# Second doc, first comment
+# Second doc, second comment
+message: nice to be here
+
+```
+
+<!-- livebook:{"output":true} -->
+
+```
+:ok
+```