yaml(3tcl)

✨ yaml — YAML Format Encoder/Decoder ✨

okay bestie, welcome to the yaml page from tcllib 🎀 this is the YAML processing manual, and yes we're about to make data exchange cute.

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require yaml ?0.4.2?

::yaml::yaml2dict ?options? txt

::yaml::yaml2huddle ?options? txt

::yaml::setOption ?options?

::yaml::dict2yaml dict ?indent? ?wordwrap?

::yaml::list2yaml list ?indent? ?wordwrap?

::yaml::huddle2yaml huddle ?indent? ?wordwrap?

---

💖 DESCRIPTION 💖

the yaml package is a simple, Tcl-only library for parsing the YAML data exchange format, exactly as specified at http://www.yaml.org/ and http://www.yaml.org/spec/1.1/. no cap, it's giving pure Tcl.

it hands your data back as a Tcl dict. so you're gonna need either the dict package or Tcl 8.5 to use it, fr fr. 🦋

---

👑 COMMANDS 👑

::yaml::yaml2dict ?options? txt

::yaml::yaml2huddle ?options? txt

these two parse yaml-formatted text txt into a Tcl dict/huddle and return that value. main character energy, honestly. 💅

• -file — txt is actually a filename of a YAML-stream. (yes, the argument name is still txt, we don't make the rules)
• -stream — txt is just a YAML-stream, as-is. periodt.
• -types list — the list is a type list for the yaml-scalar types. like, e.g. !!str !!timestamp !!integer !!true ...

-types {timestamp integer null true false}

so in this case, if a string matched "timestamp", it gets converted to the TCL internal timestamp. e.g. "2001-12-15T02:59:43.1Z" => 1008385183. iconic behaviour ngl.

• -m:true param — param is two elements of a list: the value for true, and the strings that count as it. highkey clever.

-m:true {1 {true on + yes y}}

so in this case, the string "yes" found in the YAML Stream gets automatically converted to 1. slay.

• -m:false param — param is two elements of a list: the value for false, and the strings that count as it.

-m:false {0 {false off - no n}}

• -m:null param — param is two elements of a list: the value for null, and the strings that count as it.

-m:null {"" {null nil "" ~}}

• -validate — Experiment, old: the output stream contains YAML's-tag on each node. it's giving experimental, so be aware.

% puts [::yaml::load -validate {[aaa, bbb]}]
=>
!!seq {{!!str aaa} {!!str bbb}}

::yaml::setOption ?options?

changes the implicit options for the library. right now the params are the same as ::yaml::yaml2dict. and heads up bestie — arguments passed to ::yaml::yaml2dict have more priority than this setting. 💖

::yaml::dict2yaml dict ?indent? ?wordwrap?

::yaml::list2yaml list ?indent? ?wordwrap?

::yaml::huddle2yaml huddle ?indent? ?wordwrap?

these convert a dict/list/huddle object into a YAML stream. the glow-up goes the other direction. 🧚

• indent — the spaces of indent for each block node. currently the default is 2.
• wordwrap — word wrap for the YAML stream. currently the default is 40.

---

🦋 EXAMPLES 🦋

a yaml stream converted to Tcl 🌈

an example of a yaml stream converted to Tcl. a yaml stream is returned as a single item with multiple elements.

{
--- !<tag:clarkevans.com,2002:invoice>
invoice: 34843
date   : 2001-01-23
bill-to: &id001
    given  : Chris
    family : Dumars
    address:
        lines: |
            458 Walkman Dr.
            Suite #292
        city    : Royal Oak
        state   : MI
        postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
    - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments:
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.
}
=>
invoice 34843 date 2001-01-23 bill-to {given Chris family Dumars address {lines {458 Walkman Dr.
Suite #292
} city {Royal Oak} state MI postal 48046}} ship-to {given Chris family Dumars address {lines {458 Walkman Dr.
Suite #292
} city {Royal Oak} state MI postal 48046}} product {{sku BL394D quantity 4 description Basketball price 450.00} {sku BL4438H quantity 1 description {Super Hoop} price 2392.00}} tax 251.42 total 4443.52 comments {Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.}

a yaml object converted to Tcl 💜

an example of a yaml object converted to Tcl. a yaml object is returned as a multi-element list (a dict).

{
---
- [name        , hr, avg  ]
- [Mark McGwire, 65, 0.278]
- [Sammy Sosa  , 63, 0.288]
-
  Mark McGwire: {hr: 65, avg: 0.278}
  Sammy Sosa: { hr: 63, avg: 0.288}
}
=>
{name hr avg} {{Mark McGwire} 65 0.278} {{Sammy Sosa} 63 0.288} {{Mark McGwire} {hr 65 avg 0.278} {Sammy Sosa} {hr 63 avg 0.288}}

---

🙈 LIMITATIONS 🙈

okay so, the tea: 🍓

• the tag parser is not implemented. currently, tags are merely ignored. 💀
• only Anchor => Aliases ordering works. back alias-referring is not supported.
• too many braces, or too few braces. (yes, that's the whole vibe)
• not enough character set of line feeds. please use only "\n" as line breaks.

---

😭 BUGS, IDEAS, FEEDBACK 😭

this document, and the package it describes, will undoubtedly contain bugs and other problems. no cap. please report such in the category yaml of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. please also report any ideas for enhancements you may have for either the package and/or the documentation. we want the feedback, fr fr. 🫶

when proposing code changes, please provide unified diffs, i.e. the output of diff -u.

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

---

⭐ SEE ALSO ⭐

base64, huddle, json

---

💅 KEYWORDS 💅

data exchange, huddle, parsing, text processing, yaml

---

🌸 COPYRIGHT 🌸

Copyright (c) 2008 KATO Kanryu <kanryu6@users.sourceforge.net>

---

and that's the whole page, bestie 🎀 this one came from tcllib, version 0.4.2, filed under yaml(3tcl) — go forth and parse, you ate. 👑✨💖