YAML in Elm
Convert between type-safe Elm values and YAML.
This is forked from MaybeJustJames/yaml while that package is dormant.
Install
$ elm install myrho/yamland import the library in an elm file like this
import Yaml.Decode -- for decoders
import Yaml.Encode -- for encodersDocumentation
Find the documentation on Elm's package website.
Example Usage
Decoding YAML into Elm values
Say you have some YAML which looks like this:
---
- name:
first: Marie
last: Curie
occupation: [ chemist, physicist ]
age: 66
children: [ Irène, Ève ]
- name:
first: Alva
last: Myrdal
occupation: [ sociologist, diplomat, politician ]
age: 84
children: []
- name:
first: Svetlana
last: Alexievich
occupation: [ journalist, historian ]
age: 72
children: []
... to decode this, you could write
import Yaml.Decode exposing (..)
type alias Woman =
{ name : String
, occupation : List String
, age : Int
, children : Int -- number of children
}
decoder : Decoder Woman
decoder =
map4 Woman
(map2 (\first last -> first ++ " " ++ last)
(at ["name", "first"] string)
(at ["name", "last"] string))
(field "occupation" (list string))
(field "age" int)
(map List.length (field "children" (list string)))
fromString
(list decoder)
yamlString -- The string containing the YAML example above
Encoding your Elm values into YAML
Say you are manipulating Github Actions configuration files which you might model like so:
import Yaml.Encode exposing (..)
-- Top-level structure
type alias GHActions =
{ name : String
, trigger : List String
, jobs : List Action
}
type alias Action =
{ id : String
, name : String
, runsOn : String
, steps : List Step
}
type alias Step =
{ name : String
, uses : String
, run : String
}
-- top-level encoder
encodeGHA : GHActions -> Encoder
encodeGHA action =
record
[ ("name", string action.name)
, ("on", list (string action.trigger))
, ("jobs", encodeJobs action.jobs)
]
encodeJobs : List Action -> Encoder
encodeJobs actions =
actions
|> List.map (\action -> (action.id, encodeJob action))
|> record
encodeJob : Action -> Encoder
encodeJob action =
record
[ ("name", action.name)
, ("runs-on", action.runsOn)
, ("steps", list (encodeStep action.steps))
]
encodeStep : Step -> Encoder
record
[ ("name", step.name)
, ("uses", step.uses)
, ("run", step.run)
]Now that you have modelled the data and defined encoders, encoding into a YAML formatted string is done like:
-- An example Elm value that we could encode:
myAction : GHActions
myAction =
{ name = "Tests"
, trigger = ["push", "pull_request"]
, jobs = [
{ id = "test"
, name = "Test with elm-test"
, runsOn = "ubuntu-latest"
, steps = [ { name = "Test"
, uses = ""
, run = "npx elm-test"
}
, { name = "Verify examples"
, uses = ""
, run = "npm elm-verify-examples --run-tests"
}
]
}
]
}
-- A function to do the encoding / conversion
outputGHAction : String
outputGHAction =
encodeGHA myAction
|> document
|> toString 2
This will result in the YAML String:
---
name: Tests
on:
- push
- pull_request
jobs:
test:
name: Test with elm-test
runs-on: ubuntu-latest
steps:
- name: Test
uses:
run: npx elm-test
- name: Verify examples
uses:
run: npx elm-verify-examples --run-tests
...Development
The branch parser-logging contains a version of the
parser logger
by @Janiczek.
This, along with writing detailed tests using elm-test is how I've been developing this package.
Please feel encouraged and welcome to submit bugs, PRs, etc.
Tests
This package uses elm-test and elm-verify-examples.
Major Missing Features
- Testing against the official YAML test suite. #7
Copying
You are free to copy, modify, and distribute this package with attribution under the terms of the BSD-3-Clause license. See the LICENSE file for details.
