huddle(3tcl)

📦

version 2.0 · 3 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.20 · ubuntu jammy
1.21 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ huddle(3tcl) — Create and manipulate huddle object ✨

💖 NAME 💖

huddle — Create and manipulate huddle object

🌸 SYNOPSIS 🌸

okay bestie, here's the whole vibe in one code block, no cap:

package require Tcl 8.5 9

package require huddle ?0.5?

huddle create key value ?key value ...?

huddle list ?value value ...?

huddle number number

huddle string string

huddle boolean expression to evaluate as true or false

huddle true

huddle false

huddle null

huddle get object key ?key ...?

huddle gets object key ?key ...?

huddle set objectVar key ?key ...? value

huddle remove object key ?key ...?

huddle combine object1 object2 ?object3 ...?

huddle equal object1 object2

huddle append objectVar key value ?key value ...?

huddle append objectVar value ?value ...?

huddle keys object

huddle llength object

huddle type object ?key key...?

huddle strip object

huddle jsondump object ?offset? ?newline? ?begin_offset?

huddle compile spec data

huddle isHuddle object

huddle checkHuddle object

huddle to_node object ?tag?

huddle wrap tag src

huddle call tag command args

huddle addType callback

callback command ?args?

setting

get_sub src key

strip src

set src key value

remove src key value

🦋 DESCRIPTION 🦋

okay so huddle is giving generic Tcl-based serialization/intermediary format energy. right now, each node is wrapped in a tag with simple type information. 💅

when you're converting huddle-notation to other serialization formats like JSON or YAML, that type information is used to select the proper notation. and when you're going from JSON/YAML/... to huddle, their notation can be used to select the proper huddle type. so iconic. ✨

in that manner huddle can serve as a common intermediary format. periodt.

huddle-format: >
  {HUDDLE {huddle-node}}
huddle-node: >
  {tag content}
each content of tag means:
  s: (content is a) string
  L: list, each sub node is a huddle-node
  D: dict, each sub node is a huddle-node
confirmed:
  - JSON
  - YAML(generally, but cannot discribe YAML-tags)
limitation:
  - cannot discribe aliases from a node to other node.

the huddle package returns data as a Tcl dict. either the dict package or Tcl 8.5 is required for use. literally.

👑 COMMANDS 👑

here's the whole squad of commands, bestie. every single one. 🫶

huddle create key value ?key value ...? — create a huddle object as a dict. it can contain other huddle objects. main character energy fr fr.
huddle list ?value value ...? — create a huddle object as a list. it can contain other huddle objects. slay.
huddle number number — create a huddle object as a number. numbers are cute, ngl.
huddle string string — create a huddle object as a string. strings stay stringing, iykyk.
huddle boolean expression to evaluate as true or false — create a huddle object as a boolean evaluating an expression as true or false-. yes the dash is canon, don't @ me 😭.
huddle true — create a huddle object as a boolean true. true is true, no cap.
huddle false — create a huddle object as a boolean false. false is false, periodt.
huddle null — create a huddle object as a null. null is giving void vibes.
huddle get object key ?key ...? — almost the same as dict get. get a sub-object from the huddle object. key can be used to huddle-list's index.
huddle gets object key ?key ...? — get a sub-object from the huddle object, stripped. lowkey naked.
huddle set objectVar key ?key ...? value — almost the same as dict set. set a sub-object from the huddle object. key can be used to huddle-list's index.
huddle remove object key ?key ...? — almost the same as dict remove. remove a sub-object from the huddle object. key can be used to huddle-list's index.
huddle combine object1 object2 ?object3 ...? — merging huddle objects given. obsessed.

% set aa [huddle create a b c d]
HUDDLE {D {a {s b} c {s d}}}
% set bb [huddle create a k l m]
HUDDLE {D {a {s k} l {s m}}}
% huddle combine $aa $bb
HUDDLE {D {a {s k} c {s d} l {s m}}}

huddle equal object1 object2 — comparing two huddle objects recursively. when to equal, returns 1, otherwise 0.

% set aa [huddle create a b c d]
HUDDLE {D {a {s b} c {s d}}}
% set bb [huddle create c d a b]
HUDDLE {D {c {s d} a {s b}}}
% huddle equal $aa $bb
1

huddle append objectVar key value ?key value ...?
huddle append objectVar value ?value ...? — appending child elements. when for dicts, giving key/value. when for lists, giving values. it's giving growth.

% set aa [huddle create a b c d]
HUDDLE {D {a {s b} c {s d}}}
% huddle append aa a k l m
HUDDLE {D {a {s k} c {s d} l {s m}}}
% set bb [huddle list i j k l]
HUDDLE {L {{s i} {s j} {s k} {s l}}}
% huddle append bb g h i
HUDDLE {L {{s i} {s j} {s k} {s l} {s g} {s h} {s i}}}

huddle keys object — the same as dict keys.
huddle llength object — the same as llength.
huddle type object ?key key...? — return the element type of specified by keys. if ?key? is not given, returns the type of root node.
- string — the node is a tcl's string.
- dict — the node is a dict.
- list — the node is a list.
- number — the node is a number.
- boolean — the node is a boolean.
- null — the node is a null.

% huddle type {HUDDLE {s str}}
string
% huddle type {HUDDLE {L {{s a} {s b} {s c}}}}
list
% huddle type {HUDDLE {D {aa {s b} cc {s d}}}} cc
string

huddle strip object — stripped all tags. converted to normal Tcl's list/dict. so clean.
huddle jsondump object ?offset? ?newline? ?begin_offset? — dump a json-stream from the huddle-object.
- offset "" — begin offset as spaces " ".

# normal output has some indents. some strings are escaped.
% huddle jsondump {HUDDLE {L {{L {{s i} {s baa} {s \\k} {L {{s 1.0} {s true} {s /g} {s h}}} {L {{s g}}}}} {s t}}}}
[
  [
    "i",
    "baa",
    "\\k",
    [
      1.0,
      true,
      "\/g",
      "h"
    ],
    ["g"]
  ],
  "t"
]
# stripped output
% huddle jsondump {HUDDLE {D {dd {D {bb {D {a {s baa} c {s {d
a}}}} cc {D {g {s h}}}}} ee {D {i {s j} k {s 1} j {s { m\a}}}}}}} "" ""
{"dd": {"bb": {"a": "baa","c": "d\na"},"cc": {"g": "h"}},"ee": {"i": "j","k": 1,"j": " m\\a"}}

huddle compile spec data — construct a huddle object from plain old tcl values. spec is defined as follows:
- string — data is simply a string
- list — data is a tcl list of strings
- dict — data is a tcl dict of strings
- list list — data is a tcl list of lists
- list dict — data is a tcl list of dicts
- dict xx list — data is a tcl dict where the value of key xx is a tcl list
- dict * list — data is a tcl dict of lists data is plain old tcl values

% huddle compile {dict * list} {a {1 2 3} b {4 5}}
HUDDLE {D {a {L {{s 1} {s 2} {s 3}}} b {L {{s 4} {s 5}}}}}
% huddle compile {dict * {list {dict d list}}} {a {{c 1} {d {2 2 2} e 3}} b {{f 4 g 5}}}
HUDDLE {D {a {L {{D {c {s 1}}} {D {d {L {{s 2} {s 2} {s 2}}} e {s 3}}}}} b {L {{D {f {s 4} g {s 5}}}}}}}

huddle isHuddle object — if object is a huddle, returns 1. the other, returns 0.
huddle checkHuddle object — if object is not a huddle, rises an error. (yes, "rises" — we keep it exactly, bestie 😭)
huddle to_node object ?tag? — for type-callbacks. if object is a huddle, returns root-node. the other, returns [list s $object].

% huddle to_node str
s str
% huddle to_node str !!str
!!str str
% huddle to_node {HUDDLE {s str}}
s str
% huddle to_node {HUDDLE {l {a b c}}}
l {a b c}

huddle wrap tag src — for type-callbacks. create a huddle object from src with specified tag.

% huddle wrap "" str
HUDDLE str
% huddle wrap s str
HUDDLE {s str}

huddle call tag command args — for type-callbacks. devolving command to default tag-callback.
huddle addType callback — add a user-specified-type/tag to the huddle library. to see "Additional Type".
- callback — callback function name for additional type.

💖 TYPE CALLBACK 💖

okay so this is the whole vibe for defining callbacks for a user-type, bestie. it's giving custom type energy ✨

the callback signature, periodt

callback command ?args?

command — the huddle subcomand which is needed to reply by the callback. (yes the original says "subcomand", we're keeping it, no cap)
args — arguments of subcommand. The number of list of arguments is different for each subcommand.

the subcommands ur callback has to reply to 🫶

the callback procedure shuould reply the following subcommands:

setting — only returns a fixed dict of the type infomation for setting the user-tag.
- type typename — typename of the type
- method {method1 method2 method3 ...} — method list as huddle subcommand. Then, you can call [huddle method1 ...]
- tag {tag1 child/parent tag2 child/parent ...} — tag list for huddle-node as a dict. if the type has child-nodes, use "parent", otherwise use "child".
get_sub src key — returns a sub node specified by key.
- src — a node content in huddle object.
strip src — returns stripped node contents. if the type has child nodes, every node must be stripped.
set src key value — sets a sub-node from the tagged-content, and returns self.
remove src key value — removes a sub-node from the tagged-content, and returns self.

strip must be defined at all types. get_sub must be defined at container types. set/remove shuould be defined, if you call them. (yes, "shuould" — we don't make the rules, we just keep every letter 💅)

callback sample for my-dict (iconic behavior) 🎀

# callback sample for my-dict
proc my_dict_setting {command args} {
    switch -- $command {
        setting { ; # type definition
            return {
                type dict
                method {create keys}
                tag {d child D parent}
                constructor create
                str s
            }
            # type:   the type-name
            # method: add methods to huddle's subcommand.
            #          "get_sub/strip/set/remove/equal/append" called by huddle module.
            #          "strip" must be defined at all types.
            #          "get_sub" must be defined at container types.
            #          "set/remove/equal/append" shuould be defined, if you call them.
            # tag:    tag definition("child/parent" word is maybe obsoleted)
        }
        get_sub { ; # get a sub-node specified by "key" from the tagged-content
            foreach {src key} $args break
            return [dict get $src $key]
        }
        strip { ; # strip from the tagged-content
            foreach {src nop} $args break
            foreach {key val} $src {
                lappend result $key [huddle strip $val]
            }
            return $result
        }
        set { ; # set a sub-node from the tagged-content
            foreach {src key value} $args break
            dict set src $key $value
            return $src
        }
        remove { ; # remove a sub-node from the tagged-content
            foreach {src key value} $args break
            return [dict remove $src $key]
        }
        equal { ; # check equal for each node
            foreach {src1 src2} $args break
            if {[llength $src1] != [llength $src2]} {return 0}
            foreach {key1 val1} $src1 {
                if {![dict exists $src2 $key1]} {return 0}
                if {![huddle _equal_subs $val1 [dict get $src2 $key1]]} {return 0}
            }
            return 1
        }
        append { ; # append nodes
            foreach {str src list} $args break
            if {[llength $list] % 2} {error {wrong # args: should be "huddle append objvar ?key value ...?"}}
            set resultL $src
            foreach {key value} $list {
                if {$str ne ""} {
                    lappend resultL $key [huddle to_node $value $str]
                } else {
                    lappend resultL $key $value
                }
            }
            return [eval dict create $resultL]
        }
        create { ; # $args: all arguments after "huddle create"
            if {[llength $args] % 2} {error {wrong # args: should be "huddle create ?key value ...?"}}
            set resultL {}
            foreach {key value} $args {
                lappend resultL $key [huddle to_node $value]
            }
            return [huddle wrap D $resultL]
        }
        keys {
            foreach {src nop} $args break
            return [dict keys [lindex [lindex $src 1] 1]]
        }
        default {
            error "$command is not callback for dict"
        }
    }
}

inheritance sample from default dict-callback (slay) 💅

# inheritance sample from default dict-callback
proc ::yaml::_huddle_mapping {command args} {
    switch -- $command {
        setting { ; # type definition
            return {
                type dict
                method {mapping}
                tag {!!map parent}
                constructor mapping
                str !!str
            }
        }
        mapping { ; # $args: all arguments after "huddle mapping"
            if {[llength $args] % 2} {error {wrong # args: should be "huddle mapping ?key value ...?"}}
            set resultL {}
            foreach {key value} $args {
                lappend resultL $key [huddle to_node $value !!str]
            }
            return [huddle wrap !!map $resultL]
        }
        default { ; # devolving to default dict-callback
            return [huddle call D $command $args]
        }
    }
}

✨ HOW TO ADD TYPE ✨

You can add huddle-node types e.g. ::struct::tree. To do so, first, define a callback-procedure for additional tagged-type. The proc get argments as command and ?args?. It has some switch-sections.

And, addType subcommand will called.

huddle addType my_dict_setting

🌈 WORKING SAMPLE 🌈

# create as a dict
% set bb [huddle create a b c d]
HUDDLE {D {a {s b} c {s d}}}

# create as a list
% set cc [huddle list e f g h]
HUDDLE {L {{s e} {s f} {s g} {s h}}}
% set bbcc [huddle create bb $bb cc $cc]
HUDDLE {D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}}
% set folding [huddle list $bbcc p [huddle list q r] s]
HUDDLE {L {{D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}}

# normal Tcl's notation
% huddle strip $folding
{bb {a b c d} cc {e f g h}} p {q r} s

# get a sub node
% huddle get $folding 0 bb
HUDDLE {D {a {s b} c {s d}}}
% huddle gets $folding 0 bb
a b c d

# overwrite a node
% huddle set folding 0 bb c kkk
HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}}

# remove a node
% huddle remove $folding 2 1
HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q}}} {s s}}}
% huddle strip $folding
{bb {a b c kkk} cc {e f g h}} p {q r} s

# dump as a JSON stream
% huddle jsondump $folding
[
  {
    "bb": {
      "a": "b",
      "c": "kkk"
    },
    "cc": [
      "e",
      "f",
      "g",
      "h"
    ]
  },
  "p",
  [
    "q",
    "r"
  ],
  "s"
]

😭 LIMITATIONS 😭

now printing.

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category huddle of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.

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 👑

yaml

🦋 KEYWORDS 🦋

data exchange, exchange format, huddle, json, parsing, text processing, yaml

💜 COPYRIGHT 💜

this was tcllib 0.5, huddle(3tcl) — date and version said, periodt 💅✨

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms