1huddle(n) HUDDLE huddle(n)
2______________________________________________________________________________
6
8 huddle - Create and manipulate huddle object
9
11 package require Tcl 8.4
12 package require huddle ?0.1.3?
14 huddle create key value ?key value ...?
16 huddle list ?value value ...?
18 huddle get object key ?key ...?
20 huddle gets object key ?key ...?
22 huddle set objectVar key ?key ...? value
24 huddle remove object key ?key ...?
26 huddle combine object1 object2 ?object3 ...?
28 huddle equal object1 object2
30 huddle append objectVar key value ?key value ...?
32 huddle append objectVar value ?value ...?
34 huddle keys object
36 huddle llength object
38 huddle type object ?key key...?
40 huddle strip object
42 huddle jsondump object ?offset?
44 huddle isHuddle object
46 huddle checkHuddle object
48 huddle to_node object ?tag?
50 huddle wrap tag src
52 huddle call tag command args
54 huddle addType callback
56 callback command ?args?
58 setting
60 get_sub src key
62 strip src
64 set src key value
66 remove src key value
68_________________________________________________________________
70
72 Huddle provides a generic Tcl-based serialization/intermediary format.
73 Currently, each node is wrapped in a tag with simple type information.
74 When converting huddle-notation to other serialization formats like
76 JSON or YAML this type information is used to select the proper nota‐
77 tion. And when going from JSON/YAML/... to huddle their notation can
78 be used to select the proper huddle type.
79 In that manner huddle can serve as a common intermediary format.
81 huddle-format: >
83 {HUDDLE {huddle-node}}
84 huddle-node: >
85 {tag content}
86 each content of tag means:
87 s: (content is a) string
88 L: list, each sub node is a huddle-node
89 D: dict, each sub node is a huddle-node
90 confirmed:
91 - JSON
92 - YAML(generally, but cannot discribe YAML-tags)
93 limitation:
94 - cannot discribe aliases from a node to other node.
95
98 huddle create key value ?key value ...?
99 Create a huddle object as a dict. It can contain other huddle
100 objects.
101 huddle list ?value value ...?
103 Create a huddle object as a list. It can contain other huddle
104 objects.
105 huddle get object key ?key ...?
107 Almost the same as dict get. Get a sub-object from the huddle
108 object. key can be used to huddle-list's index.
109 huddle gets object key ?key ...?
111 Get a sub-object from the huddle object, stripped.
112 huddle set objectVar key ?key ...? value
114 Almost the same as dict set. Set a sub-object from the huddle
115 object. key can be used to huddle-list's index.
116 huddle remove object key ?key ...?
118 Almost the same as dict remove. Remove a sub-object from the
119 huddle object. key can be used to huddle-list's index.
120 huddle combine object1 object2 ?object3 ...?
122 Merging huddle objects given.
123 % set aa [huddle create a b c d]
125 HUDDLE {D {a {s b} c {s d}}}
126 % set bb [huddle create a k l m]
127 HUDDLE {D {a {s k} l {s m}}}
128 % huddle combine $aa $bb
129 HUDDLE {D {a {s k} c {s d} l {s m}}}
130 huddle equal object1 object2
133 Comparing two huddle objects recursively. When to equal,
134 returns 1, otherwise 0.
135 % set aa [huddle create a b c d]
137 HUDDLE {D {a {s b} c {s d}}}
138 % set bb [huddle create c d a b]
139 HUDDLE {D {c {s d} a {s b}}}
140 % huddle equal $aa $bb
141 1
142 huddle append objectVar key value ?key value ...?
145 huddle append objectVar value ?value ...?
147 Appending child elements. When for dicts, giving key/value. When
148 for lists, giving values.
149 % set aa [huddle create a b c d]
151 HUDDLE {D {a {s b} c {s d}}}
152 % huddle append aa a k l m
153 HUDDLE {D {a {s k} c {s d} l {s m}}}
154 % set bb [huddle list i j k l]
155 HUDDLE {L {{s i} {s j} {s k} {s l}}}
156 % huddle append bb g h i
157 HUDDLE {L {{s i} {s j} {s k} {s l} {s g} {s h} {s i}}}
158 huddle keys object
161 The same as dict keys.
162 huddle llength object
164 The same as llength.
165 huddle type object ?key key...?
167 Return the element type of specified by keys. if ?key? is not
168 given, returns the type of root node.
169 string the node is a tcl's string.
172 dict the node is a dict.
174 list the node is a list.
176 % huddle type {HUDDLE {s str}}
178 string
179 % huddle type {HUDDLE {L {{s a} {s b} {s c}}}}
180 list
181 % huddle type {HUDDLE {D {aa {s b} cc {s d}}}} cc
182 string
183 huddle strip object
186 Stripped all tags. Converted to normal Tcl's list/dict.
187 huddle jsondump object ?offset?
189 dump a json-stream from the huddle-object.
190 offset ""
193 begin offset as spaces " ".
194 huddle isHuddle object
196 if object is a huddle, returns 1. the other, returns 0.
197 huddle checkHuddle object
199 if object is not a huddle, rises an error.
200 huddle to_node object ?tag?
202 for type-callbacks.
203 if object is a huddle, returns root-node. the other, returns
205 [list s $object].
206 % huddle to_node str
208 s str
209 % huddle to_node str !!str
210 !!str str
211 % huddle to_node {HUDDLE {s str}}
212 s str
213 % huddle to_node {HUDDLE {l {a b c}}}
214 l {a b c}
215 huddle wrap tag src
218 for type-callbacks.
219 Create a huddle object from src with specified tag.
221 % huddle wrap "" str
223 HUDDLE str
224 % huddle wrap s str
225 HUDDLE {s str}
226 huddle call tag command args
229 for type-callbacks.
230 devolving command to default tag-callback
232 huddle addType callback
234 add a user-specified-type/tag to the huddle library. To see
235 "Additional Type".
236 callback
239 callback function name for additional type.
240
242 The definition of callback for user-type.
243 callback command ?args?
245 command
247 huddle subcomand which is needed to reply by the call‐
248 back.
249 args arguments of subcommand. The number of list of arguments
251 is different for each subcommand.
252 The callback procedure shuould reply the following subcommands.
254 setting
256 only returns a fixed dict of the type infomation for setting the
257 user-tag.
258 type typename
260 typename of the type
261 method {method1 method2 method3 ...}
263 method list as huddle subcommand. Then, you can call
264 [huddle method1 ...]
265 tag {tag1 child/parent tag2 child/parent ...}
267 tag list for huddle-node as a dict. if the type has
268 child-nodes, use "parent", otherwise use "child".
269 get_sub src key
271 returns a sub node specified by key.
272 src a node content in huddle object.
274 strip src
276 returns stripped node contents. if the type has child nodes,
277 every node must be stripped.
278 set src key value
280 sets a sub-node from the tagged-content, and returns self.
281 remove src key value
283 removes a sub-node from the tagged-content, and returns self.
284 strip must be defined at all types. get_sub must be defined at con‐
286 tainer types. set/remove shuould be defined, if you call them.
287 # callback sample for my-dict
289 proc my_dict_setting {command args} {
290 switch -- $command {
291 setting { ; # type definition
292 return {
293 type dict
294 method {create keys}
295 tag {d child D parent}
296 constructor create
297 str s
298 }
299 # type: the type-name
300 # method: add methods to huddle's subcommand.
301 # "get_sub/strip/set/remove/equal/append" called by huddle module.
302 # "strip" must be defined at all types.
303 # "get_sub" must be defined at container types.
304 # "set/remove/equal/append" shuould be defined, if you call them.
305 # tag: tag definition("child/parent" word is maybe obsoleted)
306 }
307 get_sub { ; # get a sub-node specified by "key" from the tagged-content
308 foreach {src key} $args break
309 return [dict get $src $key]
310 }
311 strip { ; # strip from the tagged-content
312 foreach {src nop} $args break
313 foreach {key val} $src {
314 lappend result $key [huddle strip $val]
315 }
316 return $result
317 }
318 set { ; # set a sub-node from the tagged-content
319 foreach {src key value} $args break
320 dict set src $key $value
321 return $src
322 }
323 remove { ; # remove a sub-node from the tagged-content
324 foreach {src key value} $args break
325 return [dict remove $src $key]
326 }
327 equal { ; # check equal for each node
328 foreach {src1 src2} $args break
329 if {[llength $src1] != [llength $src2]} {return 0}
330 foreach {key1 val1} $src1 {
331 if {![dict exists $src2 $key1]} {return 0}
332 if {![huddle _equal_subs $val1 [dict get $src2 $key1]]} {return 0}
333 }
334 return 1
335 }
336 append { ; # append nodes
337 foreach {str src list} $args break
338 if {[llength $list] % 2} {error {wrong # args: should be "huddle append objvar ?key value ...?"}}
339 set resultL $src
340 foreach {key value} $list {
341 if {$str ne ""} {
342 lappend resultL $key [huddle to_node $value $str]
343 } else {
344 lappend resultL $key $value
345 }
346 }
347 return [eval dict create $resultL]
348 }
349 create { ; # $args: all arguments after "huddle create"
350 if {[llength $args] % 2} {error {wrong # args: should be "huddle create ?key value ...?"}}
351 set resultL {}
352 foreach {key value} $args {
353 lappend resultL $key [huddle to_node $value]
354 }
355 return [huddle wrap D $resultL]
356 }
357 keys {
358 foreach {src nop} $args break
359 return [dict keys [lindex [lindex $src 1] 1]]
360 }
361 default {
362 error "$command is not callback for dict"
363 }
364 }
365 }
366 # inheritance sample from default dict-callback
369 proc ::yaml::_huddle_mapping {command args} {
370 switch -- $command {
371 setting { ; # type definition
372 return {
373 type dict
374 method {mapping}
375 tag {!!map parent}
376 constructor mapping
377 str !!str
378 }
379 }
380 mapping { ; # $args: all arguments after "huddle mapping"
381 if {[llength $args] % 2} {error {wrong # args: should be "huddle mapping ?key value ...?"}}
382 set resultL {}
383 foreach {key value} $args {
384 lappend resultL $key [huddle to_node $value !!str]
385 }
386 return [huddle wrap !!map $resultL]
387 }
388 default { ; # devolving to default dict-callback
389 return [huddle call D $command $args]
390 }
391 }
392 }
393
396 You can add huddle-node types e.g. ::struct::tree. To do so, first,
397 define a callback-procedure for additional tagged-type. The proc get
398 argments as command and ?args?. It has some switch-sections.
399 And, addType subcommand will called.
401 huddle addType my_dict_setting
403
406 # create as a dict
407 % set bb [huddle create a b c d]
408 HUDDLE {D {a {s b} c {s d}}}
409 # create as a list
411 % set cc [huddle list e f g h]
412 HUDDLE {L {{s e} {s f} {s g} {s h}}}
413 % set bbcc [huddle create bb $bb cc $cc]
414 HUDDLE {D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}}
415 % set folding [huddle list $bbcc p [huddle list q r] s]
416 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}}}
417 # normal Tcl's notation
419 % huddle strip $folding
420 {bb {a b c d} cc {e f g h}} p {q r} s
421 # get a sub node
423 % huddle get $folding 0 bb
424 HUDDLE {D {a {s b} c {s d}}}
425 % huddle gets $folding 0 bb
426 a b c d
427 # overwrite a node
429 % huddle set folding 0 bb c kkk
430 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}}}
431 # remove a node
433 % huddle remove $folding 2 1
434 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}}}
435 % huddle strip $folding
436 {bb {a b c kkk} cc {e f g h}} p {q r} s
437 # dump as a JSON stream
439 % huddle jsondump $folding
440 [
441 {
442 "bb": {
443 "a": "b",
444 "c": "kkk"
445 },
446 "cc": [
447 "e",
448 "f",
449 "g",
450 "h"
451 ]
452 },
453 "p",
454 [
455 "q",
456 "r"
457 ],
458 "s"
459 ]
460
463 now printing.
464
466 This document, and the package it describes, will undoubtedly contain
467 bugs and other problems. Please report such in the category huddle of
468 the Tcllib SF Trackers [http://source‐
469 forge.net/tracker/?group_id=12883]. Please also report any ideas for
470 enhancements you may have for either package and/or documentation.
471
473 yaml
474
476 data exchange, exchange format, huddle, json, parsing, text processing,
477 yaml
478
480 Copyright (c) 2008 KATO Kanryu <kanryu6@users.sourceforge.net>
481yaml 0.1.3 huddle(n)