YAML is a flexible data serialization format that is designed to be easily read and written by human beings.
This library parses YAML documents into native Julia types and dumps them back into YAML documents.
For most purposes there is one important function: YAML.load, which takes a
string and parses it the first YAML document it finds.
To parse a file use YAML.load_file, and to parse every document in a file
use YAML.load_all or YAML.load_all_file.
Given a YAML document like the following
receipt: Oz-Ware Purchase Invoice
date: 2012-08-06
customer:
given: Dorothy
family: Gale
items:
- part_no: A4786
descrip: Water Bucket (Filled)
price: 1.47
quantity: 4
- part_no: E1628
descrip: High Heeled "Ruby" Slippers
size: 8
price: 100.27
quantity: 1
bill-to: &id001
street: |
123 Tornado Alley
Suite 16
city: East Centerville
state: KS
ship-to: *id001
specialDelivery: >
Follow the Yellow Brick
Road to the Emerald City.
Pay no attention to the
man behind the curtain.It can be loaded with
import YAML
data = YAML.load_file("test.yml")
println(data)Which will show you something like this.
{"date"=>Aug 6, 2012 12:00:00 AM PDT,"ship-to"=>{"street"=>"123 Tornado Alley\nSuite 16\n","state"=>"KS","city"=>"East Centerville"},"customer"=>{"given"=>"Dorothy","family"=>"Gale"},"specialDelivery"=>"Follow the Yellow Brick\nRoad to the Emerald City.\nPay no attention to the\nman behind the curtain.\n","items"=>{{"price"=>1.47,"descrip"=>"Water Bucket (Filled)","part_no"=>"A4786","quantity"=>4} … {"price"=>100.27,"size"=>8,"descrip"=>"High Heeled \"Ruby\" Slippers","part_no"=>"E1628","quantity"=>1}},"bill-to"=>{"street"=>"123 Tornado Alley\nSuite 16\n","state"=>"KS","city"=>"East Centerville"},"receipt"=>"Oz-Ware Purchase Invoice"}
Note that ints and floats are recognized, as well as timestamps which are parsed into CalendarTime objects. Also, anchors and references work as expected, without making a copy.
Dictionaries are parsed into instances of Dict{Any,Any} by default.
You can, however, specify a custom type in which to parse all dictionaries.
# using Symbol keys
data = YAML.load_file("test.yml"; dicttype=Dict{Symbol,Any})
# maintaining the order from the YAML file
using OrderedCollections
data = YAML.load_file("test.yml"; dicttype=OrderedDict{String,Any})
# specifying a default value
using DataStructures
data = YAML.load_file("test.yml"; dicttype=()->DefaultDict{String,Any}(Missing))Similar to reading files, you can emit Julia objects to YAML files by calling
write_file, or to a string object by calling write.
For example, you can reproduce the above file from the variable data
import YAML
YAML.write_file("test-output.yml", data)which gives you (omitting the precise format but maintaining the content)
receipt: "Oz-Ware Purchase Invoice"
items:
- part_no: "A4786"
price: 1.47
descrip: "Water Bucket (Filled)"
quantity: 4
- part_no: "E1628"
price: 100.27
size: 8
descrip: "High Heeled "Ruby" Slippers"
quantity: 1
customer:
given: "Dorothy"
family: "Gale"
ship-to:
city: "East Centerville"
street: |
123 Tornado Alley
Suite 16
state: "KS"
bill-to:
city: "East Centerville"
street: |
123 Tornado Alley
Suite 16
state: "KS"
specialDelivery: |
Follow the Yellow Brick Road to the Emerald City. Pay no attention to the man behind the curtain.
date: 2012-08-06- When writing YAML files, you cannot use additional constructors like you can when reading.
- Parsing sexigesimal numbers.
- Fractions of seconds in timestamps.
- Specific time-zone offsets in timestamps.
- Application specific tags.